Copyright: Contents © 1997-2001 by RITLabs S.R.L. All rights reserved.


What's new in version 3

The Bat! 3.0 has taken the developers a year of work in close contact with users to achieve their goals.

Amongst all the improvements the most visually outstanding is the new look user interface. The opportunity to replace the default interface glyphs with those of your own preference has been expanded: you can now use transparent images and new formats of graphic files. You will soon be able to download alternative glyph sets from our website www.ritlabs.com.

The Sorting Office has a new flow chart style front end, which really simplifies the management of message filtering.

The Bat! 3.0 includes new Virtual Folder technology to help you organize your email even more effectively. This allows you to create lists of messages gathered as a cross-section from anywhere in your email database using a comprehensive filtering system.

The new Mail Chat feature allows you to communicate with your correspondents instantaneously using regular e-mail messages as an underlying technology. The strong point of this approach is that unlike other instant messenger programs, The Bat! mail chat doesn't compromise the safety of your computer. Communication takes place through your trusted mail servers, and in addition the chat messages are checked by Anti-Virus and Anti-Spam filters.

The Bat! 3.0 has a Bayesian filtering plug-in as a part of the default installation. Bayesian filtering is one of the most effective spam detection algorithms available nowadays. The BayesIt! plug-in also detects URLs used in spam messages, making filtering even more efficient. First, you must train the plug-in by feeding it spam and non-spam messages, then it will do the job for you.

You are now able to connect to Microsoft Exchange Servers using The Bat! via native MAPI protocol to fetch or send messages.

The Bat! 3.0 now has a new MSI-based digitally signed installation package. You can verify the digital signature before installing The Bat! to make sure that the program comes from a trusted source and hasn't been modified in transit. System administrators now have the ability to deploy The Bat! easily throughout their networks.


About This Help System
The Bat!

SecureBat! (Pro and Lite versions)

Help System

This help system contains reference information for The Bat!, Ritlabs AuthenticBat! and Ritlabs SecureBat!

The Bat! is a powerful, highly configurable, yet easy to use email client. It has been specially designed to help users deal with the growing volume of email as quickly and efficiently as possible, saving much of the user's precious time. The Bat! is a great email client with every feature that an advanced user needs, yet with an interface that even a novice will love. See the General Information topic for a more detailed description of The Bat!

SecureBat! is an e-mail client which offers all of the major features of The Bat! plus secure authentication on POP3/SMTP servers using hardware security tokens and transparent, on-the-fly encryption of the message base, address books and configuration files using the SecureBat! ID. Upgrade from The Bat! or Ritlabs AuthenticBat! can be made by backing up all of the data using the Maintenance Centre of The Bat! or Ritlabs AuthenticBat! and then restoring the data from the Maintenance Centre of the Ritlabs SecureBat!. The potential area of use for Ritlabs SecureBat! is wide: from big corporations to small offices, home offices or private computers, where the role of the Security Officer is taken by the user themselves. Hardware security tokens for Ritlabs SecureBat! are configured by a Security Officer using a companion utility: Ritlabs SecureBat! Token Manager.

To avoid overhead, in the help system, SecureBat! is referred to as "The Bat! ", except where explicitly stated. Everything written as being about "The Bat! " also applies to SecureBat! except where explicitly stated.


Legal Information

Information in this help system is subject to change without notice and does not represent a commitment on the part of RITLABS S.R.L. The software and/or files described in this help system are furnished under a license agreement. The software and/or files may be used or copied only in accordance with the terms of the agreement. No part of this online help system may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or information and retrieval systems, for any purpose other than the purchaser's personal use, without the written permission of RITLABS S.R.L.

RITLABS S.R.L. may have patents or pending patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. The furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property rights except as expressly provided in any written license agreement from RITLABS S.R.L..

All attempts have been made to make the information in this help system complete and accurate. RITLABS S.R.L. is not responsible for any direct or indirect damages or loss of business resulting from inaccuracies or omissions. The specifications contained in this help system are subject to change without notice.

Mail Ticker™ is a trademark of RITLABS S.R.L.. Microsoft Windows, Microsoft Windows NT, Windows 95, Windows 98 and Windows 2000 are trademarks of Microsoft Corporation. All other product names referenced herein are trademarks or registered trademarks of their respective manufacturers.

Copyright © 1997-2004 RITLABS S.R.L.. All rights reserved.

Using The Bat! as a Mailing List Server chapter copyright © 1998-2004 by Leif Gregory. All rights reserved.

Regular Expressions Syntax (Advanced) chapters are written by Philip Hazel and copyright by the University of Cambridge, England.

Topics related to Ritlabs SecureBat! and Ritlabs AuthenticBat! are written by RITLABS S.R.L. and edited by Marck D. Pearlstone, copyright © 2004 RITLABS S.R.L.. All rights reserved.


Registering your copy of The Bat!

If you intend to use The Bat! after the trial period of 30 days, you must register your copy of The Bat! or stop using it. When you register The Bat!, you are eligible to receive Technical support from The Bat! support team. Features for registered users can also be used once The Bat! has been registered.

 Note: If you are a user at a location where there is a valid site license, you do not need to register. Contact your organisation's e-mail administrator for support.

To get the latest licence prices and register your copy on-line using a credit card, please visit The Bat! official WWW home page located at http://www.ritlabs.com/the_bat/ or contact The Bat! support team via e-mail at info@thebat.net


Technical support

If, after reviewing all of the available materials, you are still in need of assistance, contact your e-mail administrator (your Internet Service Provider or your company's The Bat! support coordinator) or The Bat! Support team. If you are eligible for technical support, select "Feedback | Information request" from the Help menu.

You must register your copy of The Bat! to receive technical support. See Registering Your Copy of The Bat! for details.


Entering Registration Key

The registration key is a special kind of data used by The Bat! to determine whether you can use it after the trial period of 30 days is expired. Registration keys are normally sent to users via e-mail. When an unregistered copy of The Bat! receives a message with registration key and the message is read, the key is automatically read from the message and the copy becomes registered as soon as the user switches from the message - a message box about registration is displayed.

When a message with registration key is marked as read by filters or received using another e-mail program, it is needed to enter the key using the Help|Enter Registration Code menu command of the main window. Please do not try to type the key data in manually because it is very easy to make a typo; Copy and Paste operations should be used instead.

Important: it is strongly recommended to backup your data using the Tools|Backup menu command  as soon as you have your registration key entered. This way, you will be able to restore your registration whenever you install The Bat! on a new system or after recovering from a system failure.


General Information

The Bat! is an Internet e-mail program. The primary purposes of The Bat! are:

 - Providing an efficient way of processing large numbers of messages;

 - An easy-to-use user interface;

 - Allowing users to work easily with several mail accounts and to ease the exchange of messages between them;

 - Keeping working delays to a minimum. The Bat! makes extensive use of Windows' multitasking capabilities. This means that the user can send and receive e-mail while reading or writing other mail;

 - Providing a truly multi-lingual interface. The Bat! communicates with the user in various languages - the interface's language can be chosen on-the-fly from the main program menu.

The Bat! also allows the user to pre-process mail on the mail server - without actually downloading messages to the local hard drive. The Bat! has a versatile and comfortable built in message editor with many useful functions, an Address Book and it provides an extensive set of tools for processing your mail. When connecting to POP3/SMTP servers, users of Ritlabs AuthenticBat! or Ritlabs SecureBat! can use hardware authentication based on a security token.

The program has been developed mainly for business messaging, which is why we have tried to provide as comfortable an interface as possible, without cluttering the workplace with an excessive quantity of rarely used or "just for fun" interface elements.

Major features of The Bat! are:

- Real-time automatic spellchecker. As you type, it underlines questionable spellings, and a single right click will let you choose the correct spelling and a double right click will simply auto-correct the error.

- Full 32 bit multithreading means that you can check mail on all of your accounts, and write/read messages at the same time.

- Fast, browser-independent HTML Mail viewer.

- Quick Templates allow you to save hours of typing and repetitive keystrokes by inserting pre-defined text blocks (even from disk files) and context specific information as well as attaching files and vCards and invoking PGP features without using menu commands.

- Threading messages by reference, subject, sender and recipient. This feature is especially handy for subscribers to discussion mailing lists.

- Mail Ticker™ is a feature unique to The Bat!. It looks like a Wall Street stock ticker, but it shows you the header info from your new messages - From, To, Subject, etc.

- Powerful Filtering System. Pass data to external programs, auto-responders, macro enhanced templates for auto-responders, Selective Download filters to automatically screen messages without having to retrieve the message body etc.

- Filters and Macros are so powerful that they allow you to turn the e-mail client into a mailing list server. For example, you can run mailing lists as well as full-fledged discussion lists like MajorDomo and Listserv. All you have to do is check the POP3 account, and it will filter, modify, correct the To:, From: and Reply To: headers, then mail messages out to everyone on the list.

- Internal OpenPGP implementation based on the award-winning OpenSSL library. Allows you to encrypt messages, sign them with digital signatures, etc.. Handy digital key manager. Built in support for GnuPG, PGP 5,6,7 and 8 plus free plug ins for PGP v5.5, 6.0.2 and 6.5.x.

- Multiple accounts that can be changed freely at any time. Moreover, each folder you create to save messages in can have its own identity (To, From, Reply-to), macro enhanced templates etc.. This is one of the most powerful and endearing aspects of The Bat! You can make it do just about anything.

- Automatic mail retrieval with auto log-off

- You can import your messages with the built in import wizard from the following formats:

Microsoft Outlook Express v4.xx

Microsoft Outlook Express v5.0

Netscape Communicator v4.xx

Netscape Mail v2.xx/3.xx

Eudora Lite/Pro

Pegasus Mail v2.xx or 3.xx

- You can import address books from any client that can export to an:

LDIF File

Vcard

Comma Separated File

Tab Separated File

.INI

- and from these formats:

The Bat! Address book

Eudora Address book

Pegasus Tag File

- Support for ten different interface languages, with the capability to switch between them whenever you need to.

- A unique park function, whereby you can make a message stay where it is. No accidental deletions or moving it to the wrong folder.

- An address book function that lets you choose e-mail addresses the same way you run programs from the Windows Start button or choose favourites from the favourites dropdown menu. The address book also supports vCard files and LDAP directories as well as being able to place actual pictures of your contacts in the address book. Another feature is the ability to define macro enabled templates for *each* contact or group of contacts in your address book. This means that you can easily personalise your messages for every individual you write to.

- A powerful built -in search engine displays your results in a logical, easy to use format.

- The "Mail Dispatcher" allows you to manage your mail directly on the POP3 server.

- Provides an easy and cheap corporate mailing network server solution (multi-user capabilities), that allows users to work without a local mail server.

- Submission Forms - a tool for creating queries that can be automatically processed. A great solution for a business client-server based environment.

- Dial-up networking support, new mail notification, message actions, live URLs, nested folders, smart drag & drop, an interface suitable for beginners, yet powerful enough for the experts and more!

- Virus safe - The Bat! will warn you before it will allow you to open attachments of a dubious nature, especially executable files and files with a "double extension" keeping you and your computer safe from worm or virus infection. Unlike other e-mail software, The Bat! doesn't run scripts automatically keeping you doubly safe.


Interface Langauge
Interface Language

The Bat! is an international program, the language of its interface can be changed from the Options | Language sub-menu. The TheBat.LNG Language file must be placed alongside the program executable in the same directory. This file determines the contents of the Options | Language sub-menu.


Configuring The Bat!

After you have installed The Bat!, the program starts automatically. If you are installing The Bat! for the first time, you will be prompted for a working directory. The working directory is the most important directory for the main functions of The Bat! - all of your account home directories, the account data and address books will be stored in there by default. You also will be prompted about adding The Bat!'s icon to your Desktop, Start Menu and Send-To menu. If an account list file is found in the directory you have specified, The Bat! will automatically add the listed accounts to the configuration details of your copy of The Bat!, otherwise the New Account Wizard will open.

Enter a name for the account you want to create and specify the home directory for this account. If the home directory contains account configuration files (file names begin with 'ACCOUNT'), the data from those files will be used as the defaults for your newly created account. If you choose <default> as the home directory, The Bat! creates a sub-directory in the working directory with the same name as the account.

After you have entered a new account name and the home directory has been selected, click Next. The New Account Wizard begins walking you through the fields for which you need to enter setup information.

You will need to supply the following items in the panels of the New Account Wizard (click Next after filling out each page):

Your Name - Enter your name as you would like it to appear in the From field of all of your outgoing messages from this e-mail account, indicating to your recipients who the mail is from.

E-mail Address - Enter the e-mail address that has been assigned to you by your Internet Service Provider or your organisation's e-mail administrator. This is the address that other people will use to send you e-mail. E-mail addresses are generally of the form username@domainname, and john.smith@example.com is an example.

Organisation - The name of the organisation that you represent (if any). This information about the name of your organisation is placed in the header of all of the messages you write. 'Mythical Software, Inc' is an example. If you do not want to identify your organisation, leave this field blank.

In the next window you are prompted to choose which protocol to use to access your mail server. You can choose either POP3 (Post Office Protocol v3) or IMAP (Internet Messages Access Protocol).

POP3 Server - All of your incoming e-mail messages are delivered to your incoming e-mail account, which resides on a computer that runs your incoming e-mail server. Once your messages arrive at your mail account, The Bat! picks them up and transfers them to your PC.

IMAP Server - Accessing your e-mail messages directly on the on e-mail server. It permits a client email program to access a remote message store as if it was local. By using IMAP you can  manipulate your messages from a desktop computer at home, a workstation at the office, and a notebook computer while traveling, without the need to transfer messages or files back and forth between these computers.

In the incoming  edit box, type the full host name (or IP numeric address, e.g. 193.219.214.39) of the computer that runs your incoming e-mail server: mail.ritlabs.com is an example.

SMTP Server - To send messages in The Bat!, you must have access to a computer running an SMTP (Simple Mail Transfer Protocol) server. Your outgoing messages are sent to the SMTP server, which delivers them to your recipients. The address may be represented as a traditional Internet host name (e.g.: mail.ritlabs.com) or as an IP numeric address (e.g. 193.219.214.38).  Check My Server requires authentication for sending mail to allow The Bat! making authentication on the server before sending messages.

Username - Enter the name that you will use to log in to this e-mail account. This name is provided by your Internet Service Provider or your organisation's e-mail administrator, and it usually consists of the text that appears before the at sign (@) in your return e-mail address. In the example john.smith@example.com, the login name is john.smith.

Password - Enter the password you use to access your mail server. You may leave this field blank - in this case you will be prompted to enter the password each time you try to retrieve mail. The users of Ritlabs AuthenticBat! or Ritlabs SecureBat! can use hardware authentication based on a security token.

Use secure login method (APOP) - check it if you need to perform a secured login using APOP authentication protocol

Leave copy of messages on the server - You can use your account from different places. In this case, you may want to leave messages on the server to make it possible to retrieve them from other places from which you use your mail account. If you do not want to leave copies of messages on the server, the messages will be deleted from the server mailbox after their successful retrieval.

Once you have completed setting up your account via the New Account Wizard, you are now ready to send and receive messages. However, you may need to take an additional step in order to send messages.

If the computer that runs your POP3 or IMAP server (incoming e-mail account) also runs an SMTP server, then no additional setup action is required. You are completely ready to send and receive messages in The Bat!.

If you ever wish to change the settings of your e-mail account, you can do so from the Account Properties dialog. It is available from the "Account | Properties" menu option (<Shift+Ctrl+P>) and applies to the account which is currently selected in the folder tree of the main window.


Mail Account
Setting up an E-mail Account

	This is the set of options available for the account properties (<Shift+Ctrl+P>).  For more information see: • General • Transport • Mail management • Options • Files & Directories • Templates New Message Reply Forward Reading Confirmation Save Message Cookies • Sound

Each e-mail account set-up in The Bat! has its own folder structure which is used for storing incoming, outgoing and sent messages. Other folders may have any name (depending on their use) but there are always four default folders, which cannot be deleted or renamed.

These four default folders are:

Inbox	the default incoming mail folder
Outbox	the outgoing mail folder
Sent	default folder for sent mail
Trash	folder for storing deleted messages before they are removed permanently

Each account also has its own Sorting Office / Filters settings.


General settings
Account General Settings

This section is for setting up the title of an e-mail account, as it appears in The Bat!'s account list. This is also where you define the data that is used to generate the sender's data in outgoing message headers.

Name - the name of the e-mail account. It may be any combination of characters. The only limitation is that the name must be unique within the program; in other words, there must not be another account with the same name

Edit personal certificate - use this feature to import any S/MIME or security certificates with which you have been issued.

Edit personal vCard - Invokes "Edit Address Entry" dialog box to edit your "vCard", which is like an electronic ID card which you can attach to outgoing messages. It can contain things like your name, address, contact details (personal and business), a photo and more. When you create a new messageyou can attach your personal vCard to that message from the message editor "Utilities" menu.

From name - the originator's name, which will be put in the header of each message created for the account

From address - originator's e-mail address

Organisation - organisation to which the originator belongs (if any)

Reply name - the name of the person to whom replies must be sent. Usually it is the same as the originator's name

Reply address - the e-mail address to be used for replies to an original e-mail. (the return address, and the address to which confirmations should be sent)

Default address book - The Bat! can use multiple address books. You can select an address book to be associated with this account or simply leave it set to "<default>" if you only intend to use one.

This account is the default for "mailto:" URLs - when you click on a "mailto:" link in your browser, you will want The Bat! to pick up that "mailto:" click and respond to it by creating a new message to that email address. Use this option to predetermine which account will be selected to create a message when you click on such a "mailto:" link.

Notes:

Try to avoid using characters which are not allowed in system file names (such as '+,"/\><|') in an account's name. If you need to use such special characters then you will have to specify a 'non-default directory' name for disk storage with that particular account.

Try to use only ASCII characters in the From and Reply names - this will help to avoid problems with some mail servers that don't allow non-ASCII characters in message headers.


Transport settings
Account Transport Settings

SMTP server - the address of your SMTP server to which all outgoing e-mail messages from the account will be sent. The address may be represented as a traditional URL (e.g.: mail.ritlabs.com) or as a numeric IP address (e.g. 193.219.214.38); if an IP address is used you should be aware that it could be subject to change. The advantage of using IP addresses in this context is that a DNS lookup is not used, thus it is slightly faster on connecting to the server. Generally speaking, if there are several mail accounts set in the program, it is possible to use just one SMTP server for sending messages from all accounts.

In some cases, depending on the actual SMTP server you've chosen, you may need to perform SMTP authentication. Users of Ritlabs AuthenticBat! or Ritlabs SecureBat! can make use of hardware authentication based on a security token.

Authentication - To access the SMTP Authentication options press the 'Authentication' button. From there you can choose which authentication method you wish to use:

Perform SMPT Authentication (RFC 2554) - you can opt to Use settings of Mail Retrieval, to Use specific settings, for which fields appear in which you can enter your user name and password, or to Store password on iKey, for which an iKey device is used to store the SMTP authentication password. Finally, there is an option to use MD5 security with Require secure (MD5) authentication.

Use "POP before SMTP" authentication - you can opt to use this SMTP authentication method depending on your ISP's requirements.

Mail server - the address of your POP3 or IMAP4 server on which the account's mailbox is located.  The address may be represented as a traditional URL (e.g.: mail.ritlabs.com) or as a numeric IP address (e.g. 193.219.214.38); if an IP address is used you should be aware that it could be subject to change. The advantage of using IP addresses in this context is that a DNS lookup is not used, thus it is slightly faster on connecting to the server.

User - the POP3 user name for access to your mailbox on the server. Usually, it is the same as the part of the account's e-mail address before the "@" symbol. For example, if the e-mail address is john.smith@ritlabs.com, the user's name will be john.smith

Password - the password for logging on to the POP3 server. You may leave this field blank - in this case you will be prompted to enter the password every time you try to receive mail.

Authentication - if the log in on your POP3 server allows a secure authentication mechanism, you can configure it by pressing the Authentication button, which invokes a special window. You can use the following authentication methods:

•	Regular

•	MD5 APOP Challenge/Response (RFC 1734)

•	MD5 CRAM-HMAC Challenge/Response (RFC 2095)

Users of Ritlabs AuthenticBat! or Ritlabs SecureBat! can use hardware authentication based on a security token.

•	IKey MD5 CRAM-HMAC Challenge/Response

There is a further option Do not store password, prompt on mail retrieval, which is especially useful in insecure environments as an extra security layer. If you enable this option, the Password field will be replaced by a Change Password button, which leads to the 'Authentication' dialog box.

8-bit characters are treated - this group of options allows you to set the method used to handle 8-bit (non-ASCII) characters. If you are using only the English alphabet, this feature is not very significant to you because all English characters are ASCII characters and will be sent through the net without a problem. However, if you are using accented characters or character sets other than English, you should choose the method carefully because there still are some mail servers which do not allow 8-bit characters to appear in e-mail messages. If you are not certain that the servers your messages will be passing through are capable of handling the character set you use to write your messages, it is better to choose either Base64 or Quoted-printable encoding. The difference between these two encoding methods is that Base64 produces totally unreadable text. Quoted-printable encoding can still be read if your character set is mostly Latin, in which case only accented characters are encoded. If your recipients are using The Bat! or another program which can recognise Base64 and quoted-printable encoding automatically, you may choose either of these two methods.

Delivery - the default delivery method. This is implemented mostly for defining the function of the <F2> and <Shift+F2> keystrokes for the message editor

If the delivery method is Immediate, pressing <F2> within the editor will send the message immediately, whereas if Deferred is selected, the message will be queued in Outbox.

Combined delivery - if this check box is ticked, using the "Get new mail" command will also result in the sending of queued messages from Outbox, while using the "Send queued mail" command will also result in new mail being retrieved at the same time.


Advanced transport settings
Mail management Settings

This is the section where The Bat!'s message management options and port numbers for servers are defined.

Message management

Delete received messages from server - if this method is selected, The Bat! does not leave copies of the received messages on the server. This will certainly save disk storage on your service provider's server (especially when your mailbox size is limited)

Leave messages on server - the direct opposite to the above method. This method is useful when you are accessing the server from several places and want to be able to get copies of your messages from each of those places

Keep messages on server for n days - the maximum age of messages left on the server. When a message is older than the age stated, it will be automatically deleted from the server. This means that when you opt to leave messages on the server for two days, retrieved messages will be deleted on the third day.

Delete message from server when it is removed from Trash - use this option if you want your messages to be kept on the server until you delete them and they are removed from the trash folder.

Receive header only if message size if greater than n K bytes - use this option if you do not want to receive large messages from the account. This may be useful when you are away from your usual home base and want to read only significant messages (messages of such kind are usually relatively short).

A word of warning: if you use this option in conjunction with the "Delete received messages from server" option you will not get another chance to retrieve the large message. It will be deleted without being read. It is better to use the "Keep messages on server for n days" option and then use the Message Dispatcher to retrieve the message when it is more convenient.

Message Dispatcher

Message lines to download with header - this setting determines how many lines of the message to download with the message header when viewing within the Mail Dispatcher. This allows you to read a part of a message to decide whether or not you wish to download it this session

Invoke automatically at each mail check - if this check box is ticked, the Mail Dispatcher will be invoked for each "Get new mail" command when there are new messages in the mailbox

Show all messages left on server - This option is available only if the previous option is set. If it is set, the Mail Dispatcher will show all messages left on the server, otherwise only new messages will be shown

Ports

Mail service port numbers are sometimes changed to prevent other systems from the outside world from connecting to servers used within the given network. In this case, you must re-define the port numbers.

SMTP	the port number used by SMTP protocol (default 25)

POP3	the port number used by POP3 protocol (default 110)

IMAP4	the port number used by IMAP4 protocol (default 143)


Account Preferences

POP Account

This section is designed for setting some of the miscellaneous parameters for a mail account.

Check mailbox at startup - if ticked, the "Get new mail" command is invoked automatically each time The Bat! Starts

Periodical checking each n minutes - The Bat! will automatically examine your mailbox for new mail at intervals of the defined number of minutes, if this check box is ticked. If you want to check mail even more frequently than this, you can change the drop down combo box to specify seconds instead of minutes.

Mark message as read when it is being read for - within this time period, unread messages will retain their unread status. Once an unread message has been marked as read, some actions may follow (e.g. Read Mail sorting rules, generation of Reading confirmation). These actions only take place once the newly read message is no longer being viewed.

Mark message as read only when it is open in a separate window - Use this option to restrict the previous option to only apply to messages opened in a separate window rather than the preview window.

Maximum Log file size - the account's activity Log file is stored in the account's home directory and is called ACCOUNT.LOG. To prevent this file from getting too big, you can limit its size with this parameter

Ignore "Check All Accounts" request - use this option  to prevent this account from being checked along with all your other mailboxes when you use the "Check mail for all" function (for example, when your POP3 server only works within a specific time interval).

Allow 8 bit characters in message header - use this option to enable the transmission of raw 8 bit characters (e.g. accented and umlaut characters) within message headers. Leave this unchecked to force these characters to be encoded before transmission.

Allow send/fetch without entering the access password (if any) - allows use of  send / fetch functions without first entering any account access password, i.e. for using the "Check mailbox at startup" option.

Empty Trash folder on exit - the trash folder of the account will be automatically emptied every time you exit The Bat!

These options are supplemented by the Message Editor Settings.

Confirm immediate sending - Use this option to ensure that any attempt to send a message without first queuing it in the outbox has to be confirmed first.

Enable OpenPGP - Enable OpenPGP secure messaging features.

Enable S/MIME - Enable S/MIME secure messaging features.

Sign when Completed - by default, new messages will be signed using S/MIME signing or OpenPGP signing.

Encrypt when Completed - by default, new messages will be encrypted using S/MIME encryption or OpenPGP encryption.

IMAP Account

Root folder is a path to the root folder on your IMAP server. If empty, the default value for your account set up by server's administrator is used.

Pre-defined folders give you the flexibility to change the default folders for Outbox, Sent mail and Trash.  To set up a predefined box, check the one you want to change and in the edit box enter the full path to the new folder, for example Inbox/Temp for Outbox. Note: Don't put a slash sign "/" at the end of the path

Automatically connect to server options allow you to connect automatically. You can choose from the following:

At startup invoke the Connection Centre automatically for this account when The Bat! is starting.

When account is selected connect you when you switch to your IMAP account. You can just select the account or any of the folders in it.

For managing folders connect when Manage IMAP Folders dialog is invoked

By any command enable to stay connected while you are working in your IMAP account. If you close the connection but continue working in the account, you will be connected again.

When inactive, disconnect after disconnect when you have not done any work for  a while.

The Advanced Mail Management dialog allows you to precisely set up your IMAP Mail Management. There is a Deletion tab for setting up deletion settings and an IMAP tab for IMAP related advanced options

Deletion tab

Use the following options when you are deleting your messages using <Del> or the toolbar button:

Move messages to the Trash folder is default option that, if checked, moves your messages to the Trash folder.

Mark as deleted, do not use the Trash folder deletes messages from the server without using the Trash folder.

Move to the specified folder here you can choose another folder to be used as Trash when messages are being deleted.

You can use the same options for alternative deletion. Use <Shift+Del> or the toolbar button for it.

IMAP tab

The Quick configure drop down list allows you to pick the best setting for either fast or slow connections. For example, when you are online with a fast connection it sets the refresh setting for every minute. For a slow connection it allows you not to refresh at all until except by user.

Retrieve message structures together with message headers if checked, flags such as attachments and PGP signatures in the messages preview pane will be available.

When browsing messages, retrieve only message text use this option to download only the text of messages without any attachments.

Except message smaller than if checked, you will not download messages smaller than the set size.

Compress folders when switching to another folder compresses the folder every time you switch to another

Automatically disconnect after synchronisation use this if you want to close your IMAP connection every time after you synchronise messages with the local storage.

When on-line, refresh folders every here you can set a period of time after which folders will be repeatedly synchronised.


Cookies

Cookies are typically funny phrases (aphorisms, quotations etc.) that can be inserted randomly in your messages when you use the %cookie macro in a message template. Use of cookies can lighten the tone of your messages and (hopefully) entertain your correspondents. The more cookies you use - the more colourful your messages can become.

Another great way to use cookies is to use them for greetings or one-line signatures.

Here are some examples of cookies:

Editing is a rewording activity

If you save the world too often, it begins to expect it

I like kids, but I don't think I could eat a whole one

If you want to have multi-line cookies, just introduce a \n seqence into your single line cookie at the point you want the line break.

I used to be much too conceipted\nbut now I'm perfect


Files and directories
Account Files and Directories

Home Directory  - the path to the directory where all files related to the given account are stored. This directory is also used for creating the default sub-directories (each mail folder keeps its messages in the MESSAGES.MSB file in its mail-folder directory, which by default is placed in the home directory of the account it belongs to)

Attachment management

Default encoding - the default encoding type for attachments (used by the "Attach a file" button on the toolbar of the message editor). It can be either Base64 (MIME standard) or UU-encode

You can also choose the storage method for received file attachments. They may be either kept in a separate directory (so that you can copy them from there using Windows Explorer, or the Command Prompt. This method is the most appropriate if you receive large files), or in the message bodies. If you choose to store attached files in the <default> directory, files will be stored in a sub-directory named ATTACH in the account's home directory. Attachments stored separately from message bodies may not get moved between account folders if a message body is moved.

N.B. This option is not available for SecureBat!. All attachments are stored in message bodies for security purposes. This affects mail synchronisation between SecureBat! and The Bat! message folder contents.

The Delete attached files when the message is deleted from Trash option helps The Bat! to keep your disk storage tidy, and ensures that you don't end up keeping file attachments for messages you no longer need.


New Mail Notification (Sound)

The Bat! can notify you about the arrival of new mail with a custom sound (WAV files are used, so you need a sound card installed on your machine for this to work). An account's sound settings are connected to messages arriving in any account's folders by default. It is possible to define an additional sound for user defined mail folders so you can tell just by listening into which folder new mail has arrived.

Sometimes it may be necessary to disable the sound within a certain time interval (for example, if a PC is used at home you wouldn't usually want to hear it reporting new mail in the middle of the night). Allow sound only within time interval is designed specially to restrict the times during which the New Mail Notification sound is used in such cases. Example: 9:00-20:00.


Import data from other programs

If you were using another mail program before The Bat!, you can import messages and address books from those programs into The Bat! easily.

To import messages, use the Tools|Import Messages|Mailbox Import Wizard menu command of the main window - you will see the list of the programs The Bat! can import messages from.

If you do not see the program you need listed, you may try to export messages from that program into either separate message files (with .MSG or .EML extensions) or *NIX mailboxes (usually with .MBX extension or without any extesion at all) - most of programs provide export into these formats. Once you have messages exoported, you can import them into The Bat! creating folders manually and using file import commands from the Tools|Import Messages menu while the target folder is selected.

To import address book records, open The Bat! Address Book, select the address book you wish to import records into, go to the File|Import from menu and select the format in which your program's address book is stored or exported.


Configuring Templates

Instead of boring signatures, The Bat! allows the use of powerful Templates for message creation. Templates define how a new message, reply or forward should appear before you touch the keys and start typing.

The first place where templates are defined is the Account Properties dialogue - see the Templates section and its subsections. Those templates will be used as the default for that account.

The pre-programmed template for a new message is simple:

Hello %TOFNAME,

%CURSOR

--

Best regards,

  %FROMFNAME                            mailto:%FROMADDR

This means that the first name (the %TOFNAME macro) of the recipient will be entered after the standard "Hello" greeting, the editor caret will be placed on the third line (the %CURSOR macro), the standard signature delimiter with the standard '"Best regards," below, followed by your first name (the %FROMFNAME macro) and the mailto URL with your e-mail address.

As soon as you get used to a simple yet powerful templates concept, you will be able to build more complex templates and add more professionalism (or fun) to your messaging.

Additionally, each folder, address group and address book entry can have its own set of templates. The template chosen for use in a message is done in the following order: address book entry relating to the recipient, address group, folder, account.


Tip of The Day

Each time you open The Bat! (including the first time after installation), the Bat! Tip of the Day dialog is displayed, showing you the Tip of the Day. You can display the next and previous tips by clicking the Next Tip and Previous Tip buttons. To prevent the Tip of the Day dialog from being displayed on start-up, uncheck the checkbox. You can always display the Tip of the Day from the Help menu. Click the Close button to close the Tip of the Day dialog.

You can add your own tips or your favourite quotations by editing the file named "TheBat.tip" located in the directory where The Bat! is installed. To change the order of tips, delete the file "tips.ini" located in the same directory.


Uninstalling The Bat!

You can uninstall The Bat! by using the tools provided with your Windows 95, 98, Me, NT, 2000, XP (or later) operating system. Open the Control Panel, double-click on Add/Remove Programs, select The Bat!, and click Remove.


Quitting The Bat!

To quit The Bat!, select Exit from the Message menu, or press <Alt+X>. If you have any mail retrieving or sending sessions open, you will hear the Windows exclamation sound which means that you cannot quit The Bat! at this point.

The Trash folders of accounts are emptied if the Empty Trash on exit option is on in the Account Properties. Also, all folders will process their Exit actions (purge and/or compress) which can be set in Folder properties dialog.


Checking mail

Once you have your account(s) configured, you can check your mail.

Manual checking

To check mail for a specific account manually, you should select that account in the account's tree of the main window. If you have multiple accounts, you can use the Tools|Check Mail For All menu command to invoke mail checking for all accounts (N.B. you can define accounts that won't be checked  using that command by using the "Ignore Check All Accounts request" option at the Options page of the Account Properties dialogue)

POP3 accounts:

You can retrieve mail from the mail server by clicking the Get New Mail button on the main window's toolbar. When the connection with the server is finished, you should see the result (whether new messages were received or there was an error during connection) in the log page of the main window. By default, all mail fetched from the server will be stored in the Inbox folder. You can change the way received messages are stored using rules in the Sorting Office.

You may also want to use the Message Dispatcher to preview messages on the server and selecting of messages you want to download or delete.

IMAP accounts:

Clicking the Get New Mail button initiates synchronisation of the account's folders, once synchronisation is finished, The Bat! either disconnects from the server or stays on-line - this is configured in the transport properties of the account. To configure the way folders of an IMAP account should be synchronised, use the IMAP Folder Manager (Account|IMAP Commands|Manage IMAP folders menu command).

Use the Account|IMAP Commands|Connect to the server menu command to simply get connected to the IMAP server and stay on-line.

Automatic checking

Fetching new mail for POP accounts or synchronisation of IMAP folders may also be performed automatically.

There are three ways of doing that, each of them can be used no matter whether others are used:

•	Checking mail when The Bat! starts - enable the Check mailbox at startup option at the Options page of the Account Properties dialogue

•	Periodical checking - enable the corresponding option and specify the period of checking at the Options page of the Account Properties dialogue

•	Scheduled checking - create a new event in the Scheduler (or use an existing one), configure time parameters and add a Send/Check Mail action to the start or finish action list.


Message Dispatcher

The message dispatcher is special feature of The Bat!, which lets you look at the messages stored on your POP3  mail server without downloading them. This is very useful for managing your mail remotely, for example leaving "that copy of the huge document" on the server until you get home but retrieving and reading the urgent memos while still on the mobile connection.

The Bat! lets you do this by retrieving just the headers from the mail on the server and displaying a list of  the messages like this:

The message dispatcher gets a list of the messages currently available on the server (You can choose to list all messages using <Shift+Ctrl+F2> or just new messages <Ctrl+F2>). Once you have retrieved a list of messages from the server, they are listed for you and, using the check boxes provided, you can elect to do the following to each message:

Read	Mark the message as read without downloading it
Receive	Retrieve the message into the Inbox as you would in a normal download session
Delete	Delete the message from the server without downloading it
Open	Retrieve the message into the Inbox as you would in a normal download session and then open the message in a folder view window

Once you have selected the fate of the messages in the list, press the "Execute" button [image] or the <F2> key and the selected operation will be performed on the messages as specified.


Selective Download Filters
Selective Downloads

Selective Download filters are the rules that describe which messages to accept from your POP3 server. To configure Selective Download filters for a particular account, use the Account|Sorting Office/Filters menu command and select the Selective Download section of the Sorting Office.

You can detect messages by Originator (sender), Routing information (which servers have handled the message en-route), Subject, Recipient or by examining the Entire header (all RFC 822 headers).

On the "Advanced" tab, you can choose whether to Kill or Ignore matching messages, determine what kind of match to perform with the given signal string (e.g. match with any, all, none, some, or that the signal strings contain regular expressions). You can also elect to load signal strings from a file.

Selective download filters can be used to get rid of spam (junk email) or messages infected with a virus without having to download the whole message.

N.B. Selective Download signal strings do not allow the "special syntax" used by the other types of filter, you should use Regular Expressions if some complex detection is required


General Information

POP3 (Post Office Protocol, revision 3) - the "post office" protocol is for retrieving mail from a host mail server using client software.

Once you have an e-mail address, your ISP (Internet Service Provider) should give you a user name (which is usually the same as the part of your e-mail address before the "@" symbol), a password to access your mailbox on the mail server and the address of the POP server. This should look something like "mail.host.com".

This information should be entered in the account properties, in the appropriate fields. The password may be left blank if you want to enter your POP password every time you check for new mail.

The Bat! has the ability to securely authenticate a client with a POP3 Server. This avoids the need to pass a cleartext password over a network, keeping the information private. The users of SecureBat! can use hardware authentication based on a security token.


POP3 Authentication

POP3 authentication is configured in a special window, which is invoked from the Account Properties -- Transport tab -- Receive Mail - Authentication button. The Bat! supports four authentication schemes, ranging from the least to the most secure. The users of Ritlabs AuthenticBat! or Ritlabs SecureBat! can use hardware authentication which is the most secure mechanism.

Regular - this is a simple authentication mechanism that requires an e-mail client to send a username and password to the server. Username/password data is sent in cleartext form, which could be easily intercepted in transit. This authentication mechanism is supported by most RFC-1081 compliant mail servers, e.g. mail servers that support basic POP3 features.

MD5 &APOP Challenge/Response (RFC-1939) - this authentication mechanism avoids passing a cleartext password over a network. Instead of sending the password as cleartext, the e-mail client sends a non-reversible digest (produced by the MD5 cryptographic hash function) of the password concatenated with a unique random string (Challenge String) received from the server. Any exposure of the digest that is sent during the APOP authentication cycle does not introduce a risk, even for e-mail clients that connect frequently to POP3 servers to check for new mail, e.g. every five minutes. Please note that this authentication mechanism may not be supported by all POP3 servers.

MD5 &CRAM-HMAC Challenge/Response (RFC-2095) - this authentication mechanism is an improvement over the APOP standard. It also follows a Challenge/Response scheme, but uses HMAC (Keyed-Hashing) instead of the simpler digest method. While APOP requires that both the client and server systems have access to the password in cleartext form, HMAC offers a method for avoiding such cleartext storage while retaining the algorithmic simplicity of APOP in using only MD5, though in a "keyed" mode. Another reason to choose Keyed Hashing is the greater security imparted to the authentication of short passwords. Please note that this authentication mechanism may not be supported by all POP3 servers.

Token MD-5 CRAM-HMAC Challenge/Response (available in SecureBat! Pro only) - this is a hardware implementation of the CRAM-HMAC Challenge/Response (RFC-2095) authentication. A special non-replicable hardware token is used to store the password and to produce the Keyed Hashing. When this authentication mechanism is used, the password will never be exposed at the client side. Once stored, the password cannot be extracted from the token and it is never transferred into the computer where the e-mail client is running. This way, no software (including Spies / Trojan Horses / Viruses) can intercept or otherwise retrieve the password. A mail server administrator may give the user a token that has already had the required password stored on it, so the user won't know and won't need to know the actual password. Utilising the feature that tokens can not be replicated, only the physical owner of the token will have access to the mail server, provided that he or she knows the token's PIN. All POP3 servers that support the MD5 &CRAM-HMAC Challenge/Response (RFC-2095) authentication method support this authentication mechanism. Please note that Token MD-5 CRAM-HMAC Challenge/Response authentication mechanism is available in SecureBat! Pro only.


General information

IMAP (Internet Message Access Protocol) is a method of accessing your e-mail messages directly on a mail server. It allows a email client to remotely access the message store as if it was local. By using IMAP you are able to manipulate your messages from a desktop computer at home, a workstation at the office, and a notebook computer while travelling, without the need to transfer messages or files back and forth between these computers.

IMAP allows you to fully utilize the bandwidth available to you, and unlike early POP servers (this is no longer the case), IMAP is centered on the notion that the server is your primary mail repository. Messages are always retained on the server. The client may issue commands to download them or delete them, access and set message state information, but the server always maintains the mailboxes. In

contrast to the POP approach, IMAP also allows the entire structure of a message to be transferred, which in turn provides your email client an outline of a complex MIME message without requiring the client to read the entire message and parse it locally to determine that structure. This is especially important on low-bandwidth connections. The same applies to message envelope information, which is normally presented in the message header. This information may be transferred directly, and allow the client to present a list of messages to the user in a fraction of the time it would take to transfer the entire mailbox down the wire, and parse it locally. Once a message is selected for viewing, the entire message may then be downloaded. Alternatively, the user may wish to browse only a few lines of a message, or a specific part of a multi-part MIME message. This is also possible; and is extremely advantageous on slow connections.

Note: Authentication with an IMAP server is the same as with a POP3 server.


Manage IMAP folders

Manage IMAP Folders is a facility designed to help you to set up your folders in an IMAP account. Here you can create/delete folders and sub-folders on the IMAP server as well as choose the synchronization mode for every folder in your account.

To open the Manage IMAP Folders dialog, click with the right mouse button on any folder in your IMAP account and choose the Manage IMAP Folders option. You can also start it from the Account/IMAP commands/Manage IMAP Folders sub-menu or by just using the keyboard shortcut <Alt+F7>

In the main windows of the dialog there are two tabs - All Mailboxes and Subscribed only. Under All Mailboxes there is a full list of all mailboxes stored in your IMAP server and the entire folder tree of each of them. In Subscribed only you will see a list of only those that you are subscribed to. Only these subscribed folders are available in the Folder Tree of the main window and all other places in your email client account.

Both All Mailboxes and Subscribed only tabs contain a table with the following columns:

Name	contains the name of a mailbox/folder and shows its position in the tree hierarchy.
Subscribed	check this if you want to see the selected folder in your folder structure and receive its content.
Synchronize	check this if you want to synchronise this folder regularly. If unchecked, no synchronization is ever done.
Mode if synchronised	shows you the synchronisation mode which you may change using the synchronisation mode button at the top.

At the top of the dialog there are convenient buttons: New, Delete, Synchronization mode, Reset list and Close. The 'New' button creates a new folder on server and likewise 'Delete' removes it. By using the Synchronization mode list you can change the way each folder will synchronise the local storage of messages with the server's store.

The Reset list option refreshes the tree structure in the dialog windows and retrieves settings as stored on the mail server.

A click on the Close option applies all changes made in the dialog, closes it and returns you to the main window of The Bat!


Synchronisation

In The Bat!, you can set the synchronisation mode for each folder in your IMAP account. This makes it easy for you to only to concentrate on those messages you are currently interested in, for example, to only download in full the messages you really want to see and to get only the headers for those of a lower priority.

There are two ways to set up the synchronisation mode of folders: open the Manage IMAP Folders dialog and do a fine tuning of all options or click the right mouse button on an IMAP folder and choose 'Synchronisation' from the pop-up menu. Choose one of the following options from the pop-up menu that appears:

Synchronise this folder  now	make an immediate a connection to the server (if not yet connected) and synchronise the chosen folder using one of the synchronisation options listed below.
Don't Synchronise	this option sets up the selected folder not to synchronize it at all.
Headers Only	downloads only the headers of all messages stored at the server and synchronises them with the local copies.
Headers and Text	downloads all message from the server with headers and text, but without any attachments.
Full messages	downloads all parts of the messages stored on the server, including all attachments.
New headers only	checks and synchronises the headers of only new messages.
New headers and text	synchronises the headers and bodies of new messages, but without any attachments.
New messages	synchronises all new messages at the server including all their parts.

The synchronisation option you choose will depend on the number of messages you receive in the folder, their level of importance and their average size.


Sending mail

When you have mail ready for sending out, you can...

...click the Send Queued Mail button on the main window's Toolbar or ...

...wait until your mail gets sent automatically. There are two ways to achieve that:

1.	Select the Combined Delivery option at the Transport page of the Account Properties dialogue, then go to the Options page and make sure periodical mailbox checking is enabled. Close the dialogue by cliking the OK button. Now, whenever your mailbox will be checked, all queued mail found in the Outbox folder of your account will get sent.

2.	Create a new event in the Scheduler (or use an existing one), configure time parameters and add a Send/Check Mail action to the start or finish action list, then configure the accounts you wish to send mail from for that event.


Choosing of SMTP Server

SMTP (Simple Mail Transfer Protocol) - is a simple protocol for mail transmission that is widely used on the Internet. The SMTP server's function is to receive inbound mail from other servers and clients, and to deliver outbound mail to other hosts and to its clients' mailboxes.

Usually, the address of an SMTP server is provided to you by your system administrator or Internet Service Provider. In the early years of Internet, a user might use other SMTP servers available on the Internet known to him/her, since SMTP did not require any special authorisation. Nowadays, most SMTP servers require authorisation based on either the IP address of the client, the username/password or some other form of authentication. Authorisation based on IP address does not require any special settings on the client. A server just checks what point of the Internet the client has connected from, and, if this point is within the allowed IP address range, the connection continues, and the server does not restrict the client, allowing it to send messages to any destination. Otherwise, the server may require a username/password or another authentication method, and, if the client was still not authenticated then its sending capabilities would be limited, if not completely rejected. The users of SecureBat! can use hardware authentication based on a security token.

In conclusion, in most cases, your ability to choose SMTP servers is limited and you will have to use the SMTP server provided by your system administrator or Internet Service Provider.


SMTP Authentication

SMTP authentication is configured in a special window that is invoked from the Account Properties -- Transport Tab - Send Mail - Authentication button.

Unlike POP3 authentication, SMTP authentication is optional.

The Bat!, depending on server configuration, can either authenticate according to protocols defined in RFC-2554, and/or simply logging on to a POP3 server just before initiating an SMTP session (a.k.a POP before SMTP authentication). If you are unsure of what kind authentication to choose, you can either not use SMTP authentication at all, or contact your system administrator or Internet Service Provider to find out which you really need.

Using RFC-2554, SMTP authentication involves a username and a password being transferred from the client to the server. If the username and the password for SMTP authentication are the same as for POP3 authentication, you can check "Use Settings of Mail Retrieval". Otherwise, check "Use Specific Settings" and specify the username and the password.

Regardless of which settings you are using, either specific or those of mail retrieval - you can avoid sending the password as cleartext by checking the "Require secure (MD5) authentication" box. This will activate the CRAM-HMAC Challenge/Response authentication mechanism, which, however, may not be supported by all servers.

Please note that if you check "Require secure (MD5) authentication" and the server does not support this secure authentication mechanism, there will be no authentication at all, and the mail session will continue as unauthenticated. Under no circumstances will The Bat! pass a cleartext password over a network during RFC-2554 authentication when "Require secure (MD5) authentication" is on.

Once connected to an SMTP server, The Bat! checks which of the server's RFC-2554-authentication mechanisms is available, and chooses the most secure. Even when "Require secure (MD5) authentication" is off, if the server does supports it, secure authentication will take place.

The secure (MD5) authentication mechanism avoids passing a cleartext password over a network, ensuring that it cannot be captured and used by anyone else. Instead of sending the password as cleartext, The Bat! client sends a non-reversible digest (produced by the MD5 cryptographic hash function), as defined in the HMAC (Keyed-Hashing) standard, of the password and a unique random string (Challenge String) as received from server. Even if the digest being sent is exposed during SMTP authentication, there is no risk involved, even for e-mail clients that connect frequently to SMTP servers to send new mail. Please note that this authentication mechanism may not be supported by all SMTP servers.

You may also choose the option to "Store password on token" (available in Ritlabs AuthenticBat! and Ritlabs SecureBat! only). This will activate a hardware implementation of the CRAM-HMAC Challenge/Response (RFC-2095) authentication. A special non-replicable hardware token is used to store the password and to produce Keyed Hashing. When this authentication mechanism is chosen, the password will never be exposed at the client end. Once stored, the password cannot be extracted from the token and it is never transferred into the computer where the e-mail client is running. This way, no software (including Spies / Trojan Horses / Viruses) can intercept or otherwise retrieve the password. A mail server administrator may give the user a token that has already had the required password stored on it, so the user won't even know and won't need to know the actual password. Utilising the feature that tokens cannot be replicated, only the physical owner of the token will have access to the SMTP server, provided that he or she knows the token's PIN. All SMTP servers that support MD5 &CRAM-HMAC Challenge/Response authentication support this authentication mechanism. Please note that this authentication mechanism is available in Ritlabs AuthenticBat! and Ritlabs SecureBat! only.


Problems with transferring mail

If you are experiencing any problems sending or checking your mail, the first general rule is to have a look at the account's log - use the Account|View Log  menu command of the main window when the account having the problem is selected. By examining the log records, you can turn usually up some possible reasons for the failure.

Here is a list of some common problems:

Log record: Could not connect to the server

Applies to: All protocols

Visible effects: If the log pane is enabled, you can see the error message there

Audible effects: An error sound when the failure is logged (if the error sound is enabled in global preferences)

Possible reasons and solutions:

1.	You are not connected to the Internet. You should check your connection settings and whether your networking hardware (Ethernet card, phone or cable modem, ISDN adaptor) is working and connected properly.

2.	The mail server address is wrong. Please contact your ISP or mail server administrator and ask for the correct address of your mail server.

3.	Your PC is located behind of a Firewall and requires connection through a Proxy server. You should contact your server administrator asking for the correct values for the mail server and the user name.

4.	You are using an incorrect protocol. The Bat! supports three most common protocols to access mail: POP3, IMAP4 and MAPI for MS Exchange Server. Please contact your ISP or mail server administrator and ask whether you are using the correct protocol for your account. If you are sure the protocol is correct, see No.5

5.	The port number of the mail service is incorrect. The standard port numbers are: POP3 - 110, IMAP4 - 143, SMTP - 25. These are the default values set by The Bat! when you create an account. However, some mail services require special port numbers for security reasons, so you may need to contact your ISP or mail server administrator asking whether you should use any special port numbers.

6.	The server requires secure connection (TLS). If you have been told that, ask whether you should configure your mail client to use the standard POP/IMAP/SMTP port with STARTTLS extension or you should connect to a special dedicated port. Secured connections to a dedicated port using a standard protocol usually have the -S suffix. The standard port numbers for secure connections are: POPS - 995, IMAPS - 993, SMTPS - 465. Make sure the correct connection type is selected at the Transport page of the Account Properties dialogue.

7.	Your ISP does not allow to connect to the mail servers outside its network. You should examine the contract with your ISP and if it does mention that, you can do nothing about that. Otherwise, contact the ISP and ask them what is wrong.

Log record: Login failed

Applies to: All protocols

Visible effects: A dialogue box asking for user name and password appears on the screen, if the log pane is enabled, you can see the error message there

Audible effects: An error sound when the failure is logged (if the error sound is enabled in global preferences)

Possible reasons and solutions:

1.	Your login data is incorrect. Make sure you are using the correct user name and password for the mail server. Note that passwords are often case sensitive, so make sure the Caps Lock on your keyboard is OFF when you are typing the password in. Sometimes, the user name can also be case-sensitive, so type it exactly as it is given to you by your ISP or mail server administrator. Also, if you are connecting via a Proxy server, the user name usually has a specific format like user@server.tld, the "@" symbol is specific to the Proxy server used on your Network; in this case, you should contact the system administrator or refer to the documentation of the Proxy server.

2.	You are using an inappropriate authentication mechanism. Some servers may require a specific authentication mechanism. Find out which mechanism is required and make sure it is selected in the Authentication dialogue (which is invoked by clicking the Authentication button beside the server address).

3.	Your mailbox is being locked (POP, IMAP only). You may often see a record about that in the log, but some systems do not provide details about this type of error. The most common reason for such a failure is that your mailbox is being checked simultaneously from different places. The simplest solution would be to check your mailbox later. Alternatively, you may try to schedule mailbox checking at different times in all of the places the mailbox is being checked from; make sure there is a reasonable interval between checks to avoid conflicts (e.g. when you receive large volumes of mail, the checking gap should be wide enough so that one system collects mail before a concurrent one starts checking). This also can be a case when you have multiple accounts defined within The Bat! and they actually refer to the same mail server account. The same rule as above applies (schedule checking within  reasonable intervals) or you may use only one The Bat! account and set up your filters so mail is retrieved by one of The Bat! accounts and goes into other accounts using filters.

4.	(Not very common, but still worth a mention). You are using the wrong mail server. Make sure you have entered the correct server address on the Transport page of the Account Properties dialogue - it may be that your records got mixed up and you have picked the wrong server address - one from another account for instance.

5.	If you are 100% sure no above applies, this could be a security alarm - someone may steal your password by pretending to be your mail server. This involves rather complex technical tricks, but is still possible. Do not forget to warn your system administrator about that and you should really change the password for your mailbox.

Log record: Connection broken

Applies to: All protocols

Visible effects: If the log pane is enabled, you can see the error message there

Audible effects: An error sound when the failure is logged (if the error sound is enabled in global preferences)

Possible reasons and solutions:

1.	Networking hardware (Ethernet card, phone or cable modem, ISDN adaptor) malfunction. Check whether all your networking hardware is connected to the network, powered on and working properly.

2.	Your phone line or cable is cut off, damaged or provides poor signal. Contact your phone or cable operator and ask them to check your connection to their network.

3.	Mail server went down during the session or some unrecoverable error occurred there. It is rather unusual, but happens sometimes. Try again later.

Log record: Server reports: "We don't relay" or anything like that.

Applies to: sending mail, SMTP protocol

Visible effects: If the log pane is enabled, you can see the error message there; messages do not get sent

Audible effects: An error sound when the failure is logged and error sound is enabled in the global preferences

Possible reasons and solutions:

1.	Authentication is required for sending mail through the SMTP server. You should enable authentication in the Authentication dialogue available by clicking the Authentication button beside the SMTP server address field.

2.	You are using a different SMTP server  from the domain of the e-mail address you are using. You should either use the mail server corresponding to your address' domain or contact the server's administration asking for permission to use the mail server for sending messages addressed from whatever e-mail addresses you have.

Log record: Could not store message (file name - NNNN)

Applies to: receiving mail, POP protocol

Visible effects: If the log pane is enabled, you can see the error message there; new messages do not appear in folders

Audible effects: An error sound when the failure is logged (if the error sound is enabled in global preferences)

Possible reasons and solutions:

1.	Your disk is full. Check whether you have enough space to store your mail.

2.	The Inbox folder of the account is somehow damaged. Check integrity of your folders using the Folder|Maintenance... menu command of the main window and try to receive mail again.

If any of above does not apply, you should contact your ISP or Network System Administrator and ask them to help you to deal with this problem.


Mail reading
Reading Your Mail

Received messages can be read in the message auto-view panel located of the bottom of the main program window, or in a separate "folder view" window, which allows you to read subsequent messages from the folder. It is possible to scroll messages by pressing the <Space> key. If you use this method you will read messages from page to page, and when you reach the bottom of the current message, the first page of the next message in the folder will be shown (this applies to both the preview and the folder view windows).

When a folder message list is active, it is possible to view the message using <Alt+Arrow> and <Alt+PgUp or Alt+PgDn> keys to scroll the message text up and down in the window. <Alt+Left> and <Alt+Right> keys allow you to navigate back and forth through a remembered chain of previously viewed messages. You can use the <Del> key to remove messages you do not want to keep in your message base. Press <Enter> to open the separate "folder view" window with the current message shown. To sort messages within a folder view, with the message list showing (enabled with the "View | Message list" menu option) you can use the mouse to click on the appropriate header section or the "View | Sort by" menu option.

There are many different navigation keys with which to move around and between messages. <Ctrl+]> or Ctrl+Left Arrow (Ctrl+Alt+Left in the message preview pane) will allow you to jump to the next unread message, wherever it may be in the account.

Message lists can be "threaded".

You can set the amount of time that must pass while reading a message after which the message is marked as read (note that this setting may differ from account to account).

Any URLs in the messages you are reading will appear as highlighted URLs

Colour groups can be used to add colour to your message lists to simplify visual detection of messages of different kind.

Some messages you receive may require a Reading Confirmation message to be sent. You will optionally be asked to do so before moving to the next unread message. This will only occur when the message is read for the first time.


The Message List

The message list is a list of the messages in the currently selected or currently open folder.

The font / colour used in the message list is determined by the message list colour group settings. The "default" setting is used for general list entries.

Left click on any column header to sort the message list using the entries in that column. Click a second time to reverse the sort order.

Right click on the column header bar to select the columns to be shown and the format of those columns.

<Alt+LeftClick> on any text in the message list to quickly filter the message list to include only items matching the text clicked on. Press <Ctrl+=> to remove the filter and return to a full list of messages.

Right click on any entry in the message list to access the Messages context menu.

Type any key to begin a Quick Search of the Message list.


The MailTicker
The MailTicker™

The Mail Ticker™ is, without doubt, one of the most powerful features of The Bat!

To look at, it appears as a black band containing a scrolling list of unread message details, showing (by default) From:, To: and Subject: details. You can vary its appearance in a number of ways. The first of these is that you can determine whether it is displayed permanently, automatically or not at all. You can set this in the Options | Preferences | General dialog in the "Display Ticker" section.

The next level of customisation is available to you once the ticker itself is visible. Using the right click "Context menu", you can set the ticker to be "Always on top" so that it is not obscured by other windows. You can specify that the ticker should autozoom - meaning that, if you move (click and drag) the ticker to the top or the bottom edge of the screen, it will automatically zoom to full width. You can select a "Thin view" in which the To: names are omitted. You can select which combination of messages the ticker should display from Low, Normal and High priority and you can also specify an age range in seconds for which a message is eligible to appear in the ticker. You can vary the speed of the ticker and the font used to display the text in the ticker.

You can resize the ticker by dragging either the left or right edge and move the ticker by clicking and dragging. You can make it blatant (filling the top of the screen) or minimal (occupying just a tiny space at, or even half off the edge of the screen).

Then there's its real power. Double click any message in the ticker to open the "Ticker virtual folder". This folder is not available in any other way and is a very powerful features of The Bat! This virtual folder contains all of your new messages (the ones that appear on the ticker) in a single virtual folder. No need to navigate the folder tree to chase down new messages, you can just browse them at your leisure in a single folder. The Bat! can stay in the tool tray and let you read your mail on an uncluttered screen. When new mail arrives, it will appear in the MailTicker browser that is already open.

To take full advantage of message threading, it's best to turn on the message list (View | Message list). To see any message in the context of its thread or in its own source folder, just double click on it in the message list. The same message is then opened in a folder view window, which allows you to explore the thread and other related messages.

Now let's pass to this section where we will take a look at the options themselves.

Font – different fonts, styles and size can be applied under this menu to the Mail Ticker.

Colour – different colours can be applied to the Mail Ticker

Opacity – the transparency of the Mail Ticker can be changed by moving the slider to the left or to the right.

Auto-zoom – if you drag the Mail Ticker to a margin (top/down) of a window it will be automatically zoomed, so it will be spread from one end to the other.

Display Mail Ticker in Thin View – in that case the Mail Ticker will not be as "fat" as it is when this option is unchecked.

Always on top - the Mail Ticker will be displayed over any active window on your screen.

Folders – this allows you to select folders unread messages of which will be displayed in the Mail Ticker.

Age Limits - You can define "Message Age Limits" to restrict the messages displayed in the Mail Ticker (tm) to only those that have arrived within a certain time frame.

In this way, the ticker can be configured to only inform you of the presence of newer messages.

Scrolling speed – set the scrolling speed according to your own preferences.

Messages – only the messages with the defined message priority will be displayed in the Mail Ticker. You can tick all three levels of priority.


Message Parking

Message parking is designed to prevent accidental deletion of a valuable message. When a message is parked, you will not be able to move it to another folder, nor will it be deleted or automatically purged. It is also impossible to delete a folder that contains one or more parked messages, or contains a sub-folder which contains a parked message.

To park a message from the message list, press <Ctrl+J>. To un-park the message, press <Ctrl+D>.


Quick filtering

It is possible to quickly filter a message list to view only messages you are interested in. Here are the ways to achieve this:

Use options from the View|Display menu - you can use pre-set filters for read, unread, flagged, non-flagged, parked, unparked messages, messages with or without attachments or you can use Advanced filtering by applying more conditions together.

Alternatively, you can quickly filter messages by specific attribute - just press and hold the Alt key, then click the item you want to use as the filtering criteria: name of sender or recipient, subject, attachment flag, any other column contents. If you click in the date column, messages with the same date will match and all others will disappear from the message list.

To remove a quick filter and show all messages press Ctrl+= or use the 'All messages' option from the View|Display menu.


Quick Search

Quick Search is a tool to help you rapidly locate a matching entry in the message list. To start quick search, simply start typing whatever you want to find while the message list is selected. Alternatively, you can go to the Quick Search Bar (make sure the menu option "View|Toolbars|Quick Search" is selected) and start typing there.

As you type into the Quick Search box, the first matching message (from the currently selected message) is found and selected in the list.

There is no limit to the search text other than what can be matched. If the next letter you type has no match in the list it is removed. The selection point stays on the matched line in the message list. If you want to search for the next occurrence press Ctrl+Enter, use Shift+Ctrl+Enter to move to the previous occurrence


Reading Confirmation Receipt
Reading Confirmation Receipt Template

Whenever you receive messages with a Reading Confirmation Receipt Request, The Bat! will generate a receipt message using specified template (defined either in the account properties) unless it is configured to ignore these requests.

The options for processing Reading Confirmation Receipt Requests are described below:

Put in Outbox	generate the receipt and store it in the Outbox. This allows you to make changes to the receipt or even to delete it if you do not want it to be sent.
Send immediately	generate the receipt and send it immediately
Edit	the same as writing a reply, but the receipt template is used instead of the reply template
Ignore	one of simplest ways to finish your correspondence
Prompt before the Action	this option is functional only if one of the first three methods above are chosen. In this case you will be prompted when the receipt is about to be created,. If the action is not confirmed, the request is ignored

See also:

Macros

Regular Expressions in Macros


Colour Groups

You can define custom "Colour Groups" to define the way messages and folders are shown in message lists and in the folder tree. A message or a folder may be associated with only one colour group at a time. The meaning of association with a particular colour group totally depends on user's needs. The most common usage of colour groups is to indicate:

•	Processing state (for messages - e.g. "reviewed", "in progress", "processed")

•	Messages from/to particular persons (can be assigned by a filter)

•	Messages on particular topics or with specific keywords

For folders, association with colour groups may be needed to access to some particular folders with more ease.

Colour group settings include values for the font script, size and style as well as text and background colour. Use the "Options | Preferences" menu option to define your own custom Colour Groups for messages. Different settings can be assigned to Normal and Unread messages within a single colour group.

Use the "New" button to create a new colour group.

The "Edit" button calls a separate "Edit Colour Group" dialog to specify the appearance for a colour group.

The "Delete" button lets you delete an unwanted colour group.

The "Font" button changes the font face used in all colour groups (and therefore in all of the message lists throughout The Bat!).


Setting up message reminders

Whenever you read a message, you can set The Bat! to remind about the message later by using an option from the Specials|Remind later menu.

Using the menu options, you may choose whether you want to get notifications each day within a specified period or at the end of a specified period. Once you have chosen the most appropriate reminder method, you can configure the conditions used for determining whether to display a reminder or not - this may be helpful if you set message processing attributes (e.g. assigning to a particular colour group, flagging, forwarding). By default, a reminder will be displayed if you did not reply to the message.

If you want to cancel or edit a particular reminder, open the Scheduler  and find the corresponding event record .


Adding an e-mail address to Address Book
Adding a New Entry to the Address Book

You can invoke the Address Book using the command on the Tools menu in the main program window, or click the appropriate button on the main window toolbar.

Invoke the "New Address" entry in the Edit menu in the Address Book.

Edit the user's data, particularly his name and e-mail address - all of the other fields are optional.

The new entry may be added to the Pop-up menu of the address entry fields, if the "Add to Pop-up menu" check box is checked.

There is a lot of sophistication hidden in a simple Address book entry. You can create custommessage templates for your contacts so that the messages you create for an individual are automatically given that special personal touch.

There are other, simpler ways of adding addresses to the address book. Using the " Message -- Specials" sub-menu you can easily "Add Sender to Address Book" (<Ctrl+W>) or "Add Recipient to Address Book".(<Shift+Ctrl+W>).

You can also use Sorting Office Filters to automatically add sender and recipient addresses to the address book during the filter process. See the 'Add addresses to Address Book' section of the Sorting Office 'Filtering actions' topic for more details.


Viewing and Opening Received File Attachments

Files attached to a particular message are shown on the left of the message text as icons. You may use a right mouse click to invoke the pop-up menu with possible actions for the file you have selected, or simply double-click on the selected file to open it. The appropriate file associations should be defined in your system for this to work correctly. If they are not The Bat! may prompt you to choose an application to use to open an unregistered attachment type

To protect you from virus infection, The Bat! will warn you when you try to open files of a type which may potentially be infected with a virus. You may even be prevented from opening some file types altogether. It will be at your discretion if you want to proceed with opening an attachment following a warning.

You can change which file types The Bat! is sensitive to and in what ways using the "Options | Preferences | Warnings" configuration dialog.


Creating a New Message

There are five main ways in which to create a new message:

1. By clicking on New message button or invoking the New message command in the main program window menu. In this case you will have to enter the addressee manually or use the address pop-up menu.

2. By selecting the address required from the Address Book and invoking the New message command from there.

3. When viewing a message, if an e-mail address is highlighted, click the right mouse button and choose Write a message... command - the highlighted address will automatically be placed in the "To:" field. Alternatively, you can simply double-click on the highlighted email address.

4. By pressing <Ctrl+N>

5. By pressing a user defined "System wide hot-key" which you have previously defined to start a new mail. This keystroke is available even when The Bat! does not have the focus or is minimised in the tool-tray.

You can assign a priority to outgoing messages and request a Confirm Receipt and Reading Confirmation.

You should also be aware of the email standard "cut mark" which indicates the end of the message text and the beginning of a removable signature.


Using the Message Editor

The message editor window is invoked whenever you use edit/reply/forward to create a new e-mail message. The message editor window consists of a menu bar, a Toolbar, the message header block, the Status bar, an attachment window and the message body (text editor with Spell Checking)

Menu Bar

The menu bar provides access to the common commands that can be used while you are editing messages including:

-	saving messages in various ways

-	attaching files

-	standard editing functions such as Copy/Cut/Paste operations as well as additional functions to Paste/Copy text from/to disk files, pasting as Quotation, pasting as "formatted" text;

-	special operations like block mode switching, inserting current date/time;

-	spell checking functions;

-	OpenPGP functions and options;

-	changing view options (switching on/off header fields, original message text when replying, toolbar and header fields visibility);

-	changing message preferences such as priority, character encoding, confirmation receipt requests and the active account from which the message should be sent.

Toolbar

The toolbar consists of a series of buttons that are displayed just under the title bar. It allows you to perform more frequently used functions with  just one mouse click.

Message header

By default, Outgoing mail headers consist of six fields: From, Reply-To, To, CC, BCC, Subject and Follow up. All of these fields can be directly edited. To move the cursor from field to field, press the Tab key, use Up/Down arrows or click in the desired field with the mouse. Most header fields have a drop-down history list, which can be used for auto-complete and also can be activated by the <Alt+Down> keystroke. The history lists can be edited when on screen using the <Del> key to remove unwanted entries and the <Space> key to "Park" entries in the list.

Addressee fields (To, CC and BCC) have quick buttons to invoke the address selection dialog. You can also use the <Shift+Enter> keystroke for this. Another feature is the quick address pop-up menu which can be invoked either by pressing <Alt+Enter> or by using a right mouse click - the context menu contains addresses from the address book which have the "Add to pop-up menu" option set. When you type an address, you can press <Ctrl+Plus> to let The Bat! find an addressee with the name or address beginning with whatever you have typed, pressing <Ctrl+Plus> again takes you to the next addressee with a matching name or address.

The From and Reply-To fields contain the sender's identity and the address to which replies will be sent. These fields can be edited either directly, by choosing an alternate addresses from their drop-down lists or by selecting a different Active account from the Options menu.

The Follow up field contains the identifier of the message for which the reply has been created (empty for a new message) - this field should not usually be edited. Follow up information is used for threading. The only time when you should certainly edit the Follow up information is when you are using "Reply" to start a new topic of conversation, particularly in a public discussion mailing list. In such cases you should change the Subject and remove the Follow up information completely.

The Subject is a short piece of text indicating the contents of the message. This field can be left blank, although it is considered a point of e-mail etiquette to include a Subject with each message.

Status bar

The status bar is the line below the message body. It shows the current status of the editor and the selected message editing preferences. These are (left to right): Caret position, Modified flag, current Block mode, current Input mode, the message priority any receipt requests flags and the currently active account. The last item is the message's character set). If you click with right mouse button on any section except the first two, you'll get a pop-up menu which will allow you to change an option within a particular status panel.

See also: Text Editor


Addressing Your Message

The Bat! needs an address to be able to send your messages the same way as the postal service needs an address to be able to deliver a letter. The destination e-mail addresses are entered in "To:", "CC:" or "BCC:" fields. This is possible to do using "direct" typing, Address Book aliases or the Address Pop-Up menu (available on the right mouse button click or clicking the button at the extreme right of the input field). Multiple addresses should be separated by a semicolon.

When typing an address in the address fields, there are other ways for you to hook into the Address Book:

•	You can type the complete "Handle" of the entry as defined in the Address Book "Handle" field. When you press the Tab key to move to the next header field or click into the message editor to being typing your message.

•	You can type a part of the name of a person and then press <Ctrl+Plus>. This will fill in the address using the first address in the Address Book which part matches the address you have begun typing. Press <Ctrl+Plus> again to retrieve the next and subsequent matches.

•	You can use the "favourites menu" to access your most commonly used address book entries. This is available before you start the new message (from the "Create a new message" toolbar button) and by right clicking in the address fields of the message editor once you have created it.

Once you have learned these tricks, writing and addressing new messages becomes a very quick process.


Sending messages to multiple recipients

To send messages addressed to multiple recipients so the recipients do not see each other's addresses, it is possible to use either the "BCC:" field (switch it on with the "View|BCC" menu option in the message editor) or Mass Mailing.

When you send to a BCC list, you should put an address into the TO field anyway because some SMTP servers require it (otherwise, they make all BCC addresses visible). To address to a group from the address book, you should type the group's handle and add "<list>", e.g.: MyTestGroup <list>

While using BCC fields creates a single message sent to multiple people, Mass Mailing can create personalised messages. A recipient can see his/her name and address in the TO field and the message text contains recipient-specific information like his/her title, a greeting according to the gender defined in your address book, company name, etc.  To use the Mass Mailing feature, you should create a Quick template and set the option to use it for new messages/Mass mailing. Then, select addresses from your address book and use the "File | Mass mailing using template" menu command of the address book window...

Note that using Mass Mailing for extensive lists of recipients may use a lot of your system resources.


Message Priority

You can assign a priority to outgoing messages. The priority is only meaningful to you and your recipients - it does not affect the way mail transport systems handle the messages. New messages are created with a Normal priority by default. To change the priority of the current message, in the Message Editor Window, you can use the Priority popup or Options menu.

Unread received messages are displayed in the list with differently coloured envelopes: high priority messages are red, normal priority messages are yellow and low priority messages are blue.

The envelopes of read messages still show the original priority colour of the message but in a softer tone on the lower part of the envelope.


Confirm Receipt and Reading Confirmation

You can request that your recipient's mail server notify you when your message has arrived in the user's mailbox on the server. To do this, from the Message Editor, click on the Confirm Receipt in the pop-up or Options menu. The Confirm Receipt options may or may not work as described, depending on your recipient's SMTP server software.

You can also request that your recipient notify you when he/she has read your message. To do this, from the Message Editor, click on the Reading Confirmation in the pop-up or Options menu. When your recipients open the message and have read it, a dialog is displayed asking them to create a confirmation message, depending on Reading Confirmation Options. The Reading Confirmation options may or may not work as described, depending on how your recipient's e-mail client software is configured and whether or not it is capable of  responding to such a request.

To request receipts for all messages created from a particular account, you may configure the options at the Templates|New message page of the Account Properties dialogue.


File Attachments

This is used to send files attached to an e-mail message:

Open the message editor and enter all the information you need (i.e. addressee information, subject, and message text)

From the Utilities | Attach a file sub-menu choose the encoding type, or click the right mouse button on the attachments panel and choose the encoding type (UUE or MIME/base 64) from there. Alternatively click the "attach a file" button on the editor window toolbar. In this case the encoding will be the one you set as default for the account you are writing from. You can also use the shortcut keys: <Alt+PgUp> (attach a file using MIME/Base 64) and <Alt+PgDn> (attach a file using UUE). N.B. You shouldn't use UUE encoding unless you know for certain that it exactly what you mean and need.

In the subsequent dialog, select the file you would like to send, and press the Open button.

You can drag and drop a file from the Windows Explorer onto a newly created message. Also, dragging a file to The Bat! will result in a new message being created with the file already attached.

The Bat! is also capable of responding to Simple MAPI "Send file" commands from other applications and will create a blank new message with the file attached when it receives such a command.

In all of these cases the encoding will also be the one you set as default for the account you are writing from.


Saving a Message for Later Changes

Sometimes it may be useful to save an outgoing message either as a safeguard when typing long messages, or so that you can return to it later to make changes. You can use one of "Save" (<Ctrl+S>), "Save as draft" (<Alt+F2>) or "Autosave".

To save the current message, select Save from the File menu. Saved messages are placed in the Outbox and the saved message is shown with an hourglass symbol in the Status column. The hourglass symbol indicates that the message is not yet completed (a "draft") and thus cannot be sent from the outgoing queue.

You can continue making changes to the message or close it. If you try to close an outgoing message window without saving that version of the message, an alert is displayed asking if the message should be saved or the changes discarded. If you select Discard and the message has never been saved, the message is deleted.

To delete a draft message from the outbox, first click on the hourglass symbol then delete it normally. Alternatively, drag the message to the trash folder and answer "Yes" when prompted about moving parked messages.


Sending a Message Immediately

If you want to send your messages immediately instead of putting them in a queue to send later, use the F2 key while in the message editor (make sure that the Immediate delivery option is selected in the Account Properties, otherwise use <Shift+F2>).

To send the current message, click on the Send button (<Ctrl+Enter>/<F2>) or select Send Now (<Shift+F2>) from the Message menu. If "Immediately delivery" is the selected default option then these keystrokes are reversed. The Connection Centre window shows the progress of message transmissions.

See also: Queueing a Message to Send Later.


Queuing a Message to Send Later

If you want to put your messages in the outgoing queue (in the Outbox) to send them all together at a later time use the <F2> key while in the message editor (make sure that the Immediate delivery option is not selected in the Account properties).

To put the current message in the queue, click on the Queue button or select Queue in Outbox from the Message menu. The message window is closed, the message is saved in the Outbox without the draft mode hourglass symbol which means that the message is ready to be sent.

To send all of your queued messages, select Send Queued Mail from the Account menu of the main window or press <Shift+F2>.The Connection Centre window shows the progress of message transmissions..

See also: Sending a Message Immediately.


Text Editor

The Bat! provides a quick and easy way of editing messages. The text editor has a number of commands and useful features. The main difference between it and most other Windows-based e-mail message editors is that the text being edited is shown in exactly the same format as it will appear on the recipient's screen - no matter what system or e-mail client is running on the recipient's computer.

The Bat!'s text editor uses a "free caret" or "virtual space" method which allows you to place the cursor anywhere within the edit window and start typing. This is of great benefit for formatting tables and putting information in columns.

The command set for the message editor is described in the sections below:

Block and formatting commands.

Insertion and deletion commands.

Miscellaneous editor commands.

Cursor movement commands.

Text auto-formatting options

File attachments

Spell checking functions.

Regular Expressions

URL highlights.


Spell Checking

The Bat! implements the two most commonly used spell checking engines - Sentry Spelling-Checker Engine (SSCE) and Common Speller API (CSAPI) for Standard and Just-In-Time Spell Checking.

Sentry Spelling-Checker Engine (SSCE)

SSCE is shipped as a part of The Bat!'s installation package and comes with superb 100,000-word American English and British English dictionaries with comprehensive coverage of general words, contractions, abbreviations, and capitalised proper names. It is VERY fast - checking over 100,000 words per minute even on modest hardware (66Mhz 80486). The major advantages of SSCE are:

•	Advanced User Dictionaries - add your own words to any of up to 30 user dictionaries. Words can be added to or removed from user dictionaries at run time. Words in user dictionaries may be offered as suggestions for misspelled words.

•	Intelligent suggestions for misspelled words - SSCE can locate suggested replacements using either typographical (looks like) or phonetic (sounds like) matching. Suggestions are scored by the degree of closeness to the misspelled word, and the list of suggestions is returned in decreasing score order. The most commonly misspelled words are underlined by square-wave-line and can be corrected with a right mouse button double-click on such words.

•	Case sensitive - incorrect capitalisation (e.g., canada instead of Canada) can be reported as a misspelling. Case sensitivity can be disabled if necessary by simply setting a run-time option. Dictionaries included with SSCE contain correct capitalisation forms.

•	Low resource consumption - SSCE typically uses a maximum of 450K of memory at run time and 400K of disk space. You will really appreciate this feature!

•	Works with other applications' user dictionaries - SSCE can read and write user dictionaries created by other applications, including Microsoft Word and Microsoft Office (*.dic files).

Common Speller API (CSAPI)

The CSAPI is designed for use with all Microsoft applications that include spell-checking. CSAPI is currently provided by many vendors and used by the Microsoft Office family of products and many other applications. The CSAPI engine is not shipped as a part of The Bat! installation package, but if you have Microsoft Office installed, The Bat! will automatically detect the presence of CSAPI and uses it. CSAPI is not as fast as SSCE, but the major advantage of CSAPI is its good support for multiple languages. The list of available CSAPI dictionaries is displayed in the "Language" submenu of the "Spell Checker" menu below a horizontal splitter line. The absence of a splitter line in the "Language" submenu indicates that the CSAPI engine is not installed.

Spell Checking Functions of The Bat!

While in the Message Editor Window, you can use the Spell Checker menu. The "Automatic Checking" option activates the Just-In-Time Spell Checker, which underlines misspelled words without any speed degradation.

Right-click on a highlighted word and a popup menu displays, allowing you to choose from a list of suggestions for the correct spelling of the word. Or, choose "Ignore All" to ignore the current and all subsequent occurrences of the word. Or, choose "Add" to add the word to the user dictionary. If there are no suggestions in the dictionary for the correct spelling of the misspelled word, no suggestions will be listed in the popup menu.

It is also possible to check the text using the Standard Spell Checking dialog box (select the  "Check Entire Text" submenu option of the "Spell Checker" menu or simply press <F4>). Below is the description of Spell Checking dialog box buttons:

•	Ignore - skips the current word (the word displayed in the "Not in Directory" field) without changing it and goes on to the next misspelled word.

•	Ignore All - skips all occurrences of the current word in the message without changing it and goes on to the next misspelled word. This word will then be treated as spelled correctly during the entire current The Bat! session.

•	Change - replaces the current word with the correct word taken from the "Change To" field.

•	Change All - replaces all occurrences of the selected word in the message with the correct word taken from the "Change To" field.

•	Add - adds the current word to the current user directory. The name of the current user directory is displayed in the "Add Words To:" drop-down list.

•	Suggest - gets a list of similarly spelled words for the current word (the word displayed in the "Not in Directory" field).

•	Undo - takes the selected word from the Message Editor and puts it into the "Not in Directory" field.

•	Options  invokes the Spell Checking Engine specific options dialog box.

•	Dictionaries - invokes the Spell Checking Engine specific user dictionaries configuration dialog box.

User Dictionaries Configuration

A "User dictionary" is a file with a set of words in text form, and the usual extension is *.tlx for SSCE and *.dic for CSAPI. Words can be added to or removed from a user dictionary. User dictionaries are generally fast to access, but they take up more space per word than main dictionaries. User dictionaries can be configured using the Edit Dictionaries dialog box (select the "Dictionaries" submenu of the "Spell Checker" menu or pop-up (Right Mouse Button or <Alt+F10>) context menu on a misspelled word or from the "Dictionaries" button of the Standard Spell Checking dialog box). The Edit Dictionaries dialog box displays the entire word list and language of the current dictionary, you can easily manipulate its contents here. The file name (without path) of the current dictionary is displayed in the Dictionary/File drop-down list. This list shows all active files that are used for spell checking. You can also add an existing or create a new dictionary file by pressing the "New File" or "Add File" buttons. If you press the "Remove" button, the current file will be discarded from the list of active dictionaries. Clicking the "Import" / "Export" buttons imports / exports a user dictionary to a text file, in a one word per line format.

The main purpose of the user dictionary is allowing user to add custom words to it. There are three ways of adding a word: from the Standard Spell Check dialog box, from the Edit dictionaries dialog box and from the pop-up (Right Mouse Button or <Alt+F10>) context menu on a misspelled word.

The Bat! only checks the text that you have entered along with your template text. If your template includes words that the spell checker does not know, you can simply add them to the default user directory. Note that the user directories for different languages may vary. Quoted text and URL links are not checked.


Block Modes

Text blocks can be:

Stream - Standard - as they are in most Windows-based text processors

Linear - whole text rows are selected

Column - rectangular text areas are selected. This is based on the fact that plain text editors use only fixed pitch fonts. Column blocks are sensitive to the Insert mode of the editor. If Insert mode is on, column blocks are inserted in the text while shifting the original text the corresponding number of character positions to the right, otherwise the original text is replaced within the rectangular area of the inserted block

If Persistent blocks are used, text remains selected until you select another region, hide the selection or delete the selected text. Otherwise, the selection will be automatically hidden when you move the cursor to another position, type some text, or insert some text from the Clipboard.

The Override blocks option works only if Persistent blocks are not used. If this option is selected, selected text is replaced by anything you type in, insert from the Clipboard, or press <Del> key and selected text is deleted.


Automatic Text Formatting

When typing text, you can make use of the various auto-formatting options built into The Bat!'s message editor.

Auto wrap mode - if the length of the row you are typing in exceeds the value set as Right margin, the text will be automatically wrapped to the next row

Autoformat mode - with this option enabled, any changes you make to formatted text will result in the automatic reformatting of the text according to the current Text Formatting settings. If you don't have Autoformat mode enabled then you can use the block formatting commands to reformat text manually.

Important note: The Bat!'s editor is a plain text editor. As such, it has no way to distinguish between "hard" and "soft" carriage returns. The only way of separating paragraphs in such a case is to leave a clear blank line between paragraphs. If you have autoformat mode enabled and try to type a new paragraph into a line following the previous paragraph, the text will be auto-formatted into the preceding paragraph. The same happens if you start typing on the line before an existing paragraph.

You can use the <Shift+Ctrl+F> key combination to dynamically toggle autoformat mode on and off as you work to allow you to type lists and column formatted text in amongst the formatted paragraphs.

Justify on wrap - when a text row is automatically wrapped while typing, the text in the row is justified accordingly with the Right margin value. This is possible because The Bat! uses only fixed pitch fonts in the editor. Use the <Shift+Ctrl+J> key combination to dynamically toggle justify on wrap mode on and off as you work.

To reformat blocks of text on the fly, you can use these key strokes: place your cursor somewhere inside the paragraph and press <Alt+L>, <Alt+C>, <Alt+R>, <Alt+J> for Left Justify, Centered, Right Justified, Justified respectively. If you place the cursor inside the paragraph with the mouse, you must hit one of the arrow keys at least once to get the whole paragraph to reformat, otherwise it will only format the single line in which your cursor was positioned. You can also mark the block to be formatted with the mouse before pressing the desired reformat key.

Auto indent mode- positions the cursor under the first nonblank character of the preceding nonblank line when you press Enter.

Backspace unindents - aligns the insertion point with the previous indentation level when you press Backspace, if the cursor is on the first nonblank character of a line.


Using the Evaluate command

You can evaluate mathematical expressions when editing text. Type an expression (make sure it is selected if it contains spaces or the caret is not within it) and then use the "Utilities | Evaluate" menu command. The expression will be replaced by its evaluation result or, if the "=" sign was at the end of it, the evaluation result is added at the end of the expression.

Possible operators are: +,-,*,/,\ (remainder of integer division), ** (power), & (AND), |(OR), ^(XOR),~(NOT), && (logical AND), || (logical OR), ^^ (logical XOR), ! (logical NOT), <, >, ==, <=, >=, ? (ternary operator - (exp0)?(exp1):(exp2) calculates as exp1 if exp0 is not zero and exp2 otherwise). Note that the numbers must be in a strict form without national thousands separators and the decimal point is "." (a dot).

Examples:

1.2+2**3	is replaced by	9.2

1.2+2**3=	is replaced by	1.2+2**3=9.2

(1+2<4&&2==4)?1:100	is replaced by	100

(1+2<4&&2<=3)?1:100	is replaced by	1

This facility can be used together with the Quick Templates (specifically, with the %CLIPBOARD macro when a value is in the Clipboard) - for example, if you have formulas for different cases (price or size calculation).


Translation Tables

Character Translation Tables are designed to manage multiple national character encoding tables. For example, there are three different encoding tables used in Russia (DOS Code Page 866, Windows 1251 and KOI-8), the same situation arises in many other countries where a non-Latin alphabet or a Latin alphabet with accented characters is used.

Translation tables determine what characters of a particular alphabet correspond to their equivalents in the Windows national code page. To add a translation table to The Bat! use the Options | XLAT tables dialog. Press the Add button and select the file containing the translation table you want to add. You will need to enter the name of the table being added as it appears in the program menus. You will also need to enter the name of the character set determined by the table and as it appears in the charset field of a message header (for example, "koi8-r" for the Russian KOI-8 character set).

The format of the file containing a Translation table is fairly simple. It is a stream of character pairs: <national character 1><Windows equivalent 1><national character 2><Windows equivalent 2>...<national character n><Windows equivalent n>


Block and Formatting Commands

You can use the standard cursor keys, together with the <Shift> key to mark a block of text. Alternatively, you can use the mouse to select text by moving the mouse cursor while pressing the left mouse-button.

There are also the following standard block functions available in The Bat!'s message editor

Action	Key combination

Mark the beginning of a block	Ctrl+K B
Mark the end of a block	Ctrl+K K
Copy the block to the Clipboard	Ctrl+Ins or Ctrl+C
Cut the block to the Clipboard	Shift+Del or Ctrl+X
Paste the block from Clipboard	Shift+Ins or Ctrl+V
Paste the block from Clipboard as a quotation	Alt+Ins
Paste the block from Clipboard and reformat	Shift+Ctrl+Ins
Read the block from file	Ctrl+K R
Write the block to a file	Ctrl+K W
Move the block left to right	Ctrl+K I
Move the block to the left	Ctrl+K U
Switch block type to stream (default)	Ctrl+O K
Switch block type to column	Ctrl+O C
Switch block type to linear	Ctrl+O L
Justify the block or paragraph	Alt+J
Align the block on left end	Alt+L
Align the block on right end	Alt+R
Centre the block	Alt+C

See also:

Insertion and deletion commands.

Miscellaneous editor commands.

Cursor movement commands.


Cursor Movement Commands

Action	Key combination
Left to one character	Left arrow
Right to one character	Right arrow
Word left	Ctrl + Left arrow
Word right	Ctrl + Right arrow
Up to one row	Up arrow
Down to one row	Down arrow
To the start of the row	Home
To the end of the row	End
Scroll up to one row	Alt + Up arrow
Scroll down to one row	Alt + Down arrow
Up to one screen height	PgUp
Down to one screen height	PgDn
To the start of the text	Ctrl+Home or Ctrl+PgUp
To the end of the text	Ctrl+End or Ctrl+PgDn
To the selection start	Ctrl+Q B
To the selection end	Ctrl+Q K

See also:

Block and formatting commands.

Insertion and deletion commands.

Miscellaneous editor commands.


Insertion and Deletion Commands

Action	Key combination
Toggle Insert/Overwrite Mode	Ins
Delete the current line	Ctrl+Y
Delete to the end of line	Ctrl+Q Y
Delete character to the left	Backspace
Delete character to the right	Del
Delete word right of the cursor	Ctrl+T
Delete word left of the cursor	Ctrl+Backspace

See also:

Block and formatting commands.

Miscellaneous editor commands.

Cursor movement commands.


Signing your message with PGP
Signing your message with OpenPGP

To assure your recipients that the messages they receive are really from your e-mail address, the best way is to sign your messages with a PGP signature. OpenPGP signed messages contain their original text plus a cryptographic digest created using your key information. If somebody tries to modify a message signed by you, then that message will not be verified successfully by the recipients. OpenPGP signing can be used together with encryption.

With The Bat!, you can sign your messages from the message editor either manually using the "OpenPGP | Sign block" ("Sign entire text", "Sign and encrypt entire text") command (<Shift+Ctrl+S>) or automatically using the on/off "Sign when completed" option of the Privacy menu. You can also enable/disable signing and encryption from within your message templates using macros.

Using the Privacy menu, you can also enable the use of PGP/MIME, whereby the signature is added as an attachment instead of altering the appearance of the message with a textual "SIGNED MESSAGE" preamble and suffix.

Before sending signed messages, make sure that your recipients have a copy of your public OpenPGP key, otherwise they won't be able to verify your messages against your signature. Please refer to the manual of your particular OpenPGP implementation regarding the distribution of your public key.

See also: 	Encrypting your message with OpenPGP

Decrypting OpenPGP signed messages

Verifying OpenPGP signed messages

Adding OpenPGP public keys from a message


Encrypting your message with PGP
Encrypting your message with OpenPGP

To send messages securely over the Internet, you have the option to encrypt your messages with OpenPGP. An OpenPGP encrypted message cannot be read by anybody but the people whose public OpenPGP keys are used to encrypt the message. OpenPGP Encryption can be used together with signing.

Using The Bat!, you can encrypt your messages from the message editor either manually using one of the "OpenPGP | Encrypt entire text" (<Shift+Ctrl+E>)/"Sign and encrypt entire text" (<Shift+Alt+E>) commands  or automatically using the on/off "Encrypt when completed" option of the Privacy menu. Enable PGP/MIME to encrypt the entire message including attchments.

To encrypt your message to a particular recipient, you must have the recipient's public key on you PGP "keyring". Please refer to the manual of your particular OpenPGP implementation to learn how you can obtain public keys.

Unless you also encrypt to your own default key then you will be unable to read the message once it has been encrypted.

See also: 	Decrypting OpenPGP signed messages

Signing your message with OpenPGP

Verifying OpenPGP signed messages

Adding OpenPGP public keys from a message


Creating HTML messages

Using the HTML editor

To create a new HTML message in The Bat! just create a new message and change format in the Options/Message format menu. There are two options for HTML format:

1.	HTML only if you want to only send an HTML part in your  message.

2.	HTML/Plain text if you want the recipient to receive a copy of the html part in plain text.

It is always better to use HTML/Plain text since many internet users prefer not to read HTML based messages in their correspondence. After choosing the preferred format, a format menu will appear between the header section and the body of the message.

The HTML editor is as simple as using any Rich Format Text editor.

To change the style, colour, or font of the selected text:

1.	Select the text you want to format.

2.	From the format menu choose one of the following

Font: Use this to select a font.

Note: It is preferably to use the Helvetica, Arial, Times, and Courier fonts because they generally look the same when viewed on different computers. If you select a different font, it may not look the same when viewed using a different computer. Instead of specifying a font that may not be available to all who view your message, it's generally best to select one of the these fonts.

Size: Use this to select a font size

Text Style: Use this to select a style, such as italic, bold, or underline.

Foreground Colour: Use this to choose a text colour for letters from the colour picker. If you are familiar with HTML hexadecimal colour codes, you can type a specific code. Also you can just pick any colour from the basic colour palette or define a custom one.

Background Colour: Use this to choose a text background colour from the color picker.

Text alignment: Use this option from the format menu to choose left, right, center or justify text.

Insert Image: Use this to insert images into your HTML message.

To insert an image:

1.	With the mouse, click to a place in the message body where you want the image to appear.

2.	Click on the Insert image button on the toolbar

3.	Type the location and filename of the image file or browse directories to search for an image file on your hard drive or network.


What are templates?
Templates General Concept

Message templates are used as a basis for composing messages. They place static textual information in the message body. They may have, for example, a greeting and a signature as well as defining the location and format of quoted text for replies. From our point of view, the use of templates is a more flexible method of message composition than the use of just "signatures".

It is also possible to use macros in templates to include message-dependent information such as the name of the addressee, the subject, the current time, etc. With macros, it is also possible to change the addressee, to define additional addressees, to change the message subject and more.

Templates defined in the account's properties are used by default for all messages created within the account. It is also possible to create special templates for each mail folder - these templates will be used when the folder is selected in the main window's folder panel. Finally (and the first choice for which template to choose), templates can be associated with the address book, at the group and at the individual address level.

When generating a new message (either as a New message, a Reply or a Forwarded message) The Bat! will use these templates in reverse order. If an address book template exists for the addressee, then that will be used. If not, and an address book group template exists then that will be used. If there are no associated address book templates then the folder template is used - as specified in the currently selected folder. Finally, if none of these templates are available, then The Bat! uses the account default templates.

The current version of The Bat! supports four types of templates:

New message

Reply to a message

Forwarding of a message

Reading confirmation

Saving a message

It is possible to add "Cookies" to a message using template macros

Example of a message template

Hiya %tofname,

  %cursor

Bye now,

   %fromfname              mailto:%fromaddr

...%cookie

The initial look of new message addressed to Mike Brown <mike@domain.com> from John Smith <john@site.net> will be:

Hiya Mike,

  | - the editor cursor will be placed here by default

Bye now,

   John              mailto:john@site.net

...Put knot yore trust inn spel chequers

See also:

Macros

Regular Expressions in Macros


New Message Template

The New message template is used whenever you create a new message. Once the message editor window is opened and you have all the header information (From, To, Subject) fields filled in correctly, text will appear in the editor window, as specified by the new message template. It is also possible to define certain message options for new messages such as:

- Default character set

- Confirm Receipt Request.

- Reading Confirmation Request.

Note that these options can only be used for new messages. Replies and forwards will not use them. Also, macros relating to an "original message" will not function - they will be replaced by empty strings.

There are other macros which can be used in all message templates to define more generic options. See the full list for details:

Macros

Regular Expressions in Macros


Reply Template

A Reply template is used whenever you reply to a message you have received ("Reply" and "Reply to all" commands and the "Special" reply functions). You will see the initial reply text as soon as the Reply command is invoked. If you subsequently change anything in the message header - the initial text will be adjusted to reflect the new information unless you have changed the message before editing the header. To have the original message's text placed into the initial text of a reply, use the %QUOTES macros to include it in the mail as a quotation and %TEXT to include it as normal text.

The style of the quotation prefix is initially defined by the Sender information used for quotation option in the "Account | Properties | Templates | Reply" dialog. "Initials" is the default setting. Example (John A. Smith is used as the sender)

Option:	Prefix
None	>
Initials	JAS>
Name	John>
Last Name	Smith>
First Initial	J>
Full Name	John A. Smith>

This can be overridden within the template using the %QuoteStyle macro.

See also:

Macros

Regular Expressions in Macros


Forwarding of messages
Forward Template

There are two ways of forwarding messages: with a template, which places the original text into the message text, and using MIME to attach the file. When messages are forwarded using MIME, it is possible to send several messages enveloped within a single message (a message digest), however not all mail clients can manage MIME digests correctly.

In the case of a message forwarded by placing the original text in the message text, the template could be defined as follows:

 This is a forwarded message

 From:    %OFROMNAME <%OFROMADDR>

 To:        %OTOLIST

 Subject: %OSUBJ

-8<------------- Original message text -----------------

%TEXT

-8<--------- End of Original message text --------------

Hello %TOFNAME,

%CURSOR

Best regards,

%FROMFNAME

In the case of MIME-forwarding, the template could be:

Hello %TONAME,

 %CURSOR

All the best,

  %FROMNAME

See also:

Macros

Regular Expressions in Macros


Saving messages
Save Message Template

When you use the "Message | Save as" (<Alt+F5>) option, this template defines the formatting used to create the saved message text file on disk. You can take advantage of the full range of template macros to aid in presentation of the saved text.

See also:

Macros

Regular Expressions in Macros


Quick Templates

Quick Templates are designed to save hours of typing of similar blocks of text in your messages. This feature is extremely useful, especially when you do any kind of support via e-mail and have to repeatedly answer similar questions. With Quick Templates, it is also possible to attach files, vCards and change other message settings without having to stop typing a message to use the menus.  Note that all template macros are available in Quick Templates as in other templates used within The Bat!

Each Quick Template has a unique handle, which should be one you can easily remember. When you want to insert a Quick Template in your message, just type its handle in the text and press <Ctrl+Space> - the handle will be replaced with the text block as defined in the quick template. If you don't remember the handle, you still can use the "Utilities | Insert Quick Template" menu of the message editor.

Quick Templates are associated with an account, so you can edit them from Account Properties dialog: from the Templates page, press the "Edit Quick Templates" button (<Shift+Ctrl+Q>). It is also possible to edit Quick Templates using the "Options | Quick templates" menu command from the main program window.  If you want to share a Quick Template between other accounts, tick the appropriate check box in the template editor. A quick template can be used as the base message template for a mass mailing

There are many advanced uses from quick templates which suddenly transform the way The Bat! works. For example, if you use the %ISSIGNATURE macro in a quick template, then when you invoke that quick template, any current signature (below a cut mark) is instantly removed and replaced with the new signature from the quick template.

There is also the technique of defining constant template segments in quick templates and building your standard template from a series of %QINCLUDE="handle" macros. This way, your templates can follow a simpler format and, when you need to change a specific aspect of all of your templates, just change the quick template in which is defined and, presto, the job is done!


The complete list of Template Macros
Template Macros

A Template Macro is a special command to the template processor that generates text, sets message parameters, adds signatures to messages etc. To use a macro in a template, it must always starts with a "%" symbol, which is followed by the name and an optional parameter in double (or single) quotes.  These sections describe the available macros:

Full alphabetic list of macros	The full list in alphabetic order
Addressing macros	Macros that deal with email addresses
Name and address macros	Macros that deal with names from address
Account data macros	Macros that deal with account details and settings
Message content macros	Macros that affect the message text
Date / time macros	Macros for dealing with dates and times
Message header macros	Macros for affecting and using message header data
Regular expression and programming macros	More complex macros for programming and intelligent text manipulation
Information macros	Macros which give access to system data
Privacy macros	Macros to provide access to PGP and S/MIME functionality
Configuration macros	Macros to provide access to The Bat!'s configuration settings and data

A special note about using macro parameters:

Macro parameters can be enclosed either in double quotes or apostrophes. To use a double quote or apostrophe within a macro parameter when the enclosing quote character is the same, use a pair of the required character instead of a single one. E.g.: in %MACRO='my "double quoted" text' the macro parameter is my "double quoted" text ; it is also possible to use this construct instead: %MACRO="my ""double quoted"" text" - note the doubled double quotes inside the macro parameter.

Another option is to use "special" characters as delimiters; characters that do not appear in the parameter string:

%MACRO=_my "double quoted" text_ or %MACRO=#my "double quoted" text#

Note: The Bat! version 2 introduces a new syntax for macros: it is now possible to use brackets instead of ="..." (in some cases it is now required, for example in macros with more than one parameter). Plus, quotation marks are not required for one-word or one-macro parameters.

In most macro parameters, it is possible to embed other macros to generate even more complex text. E.g.: %TO='%QINCLUDE="MySpecialToQuickTemplate"'


Full alphabetic list of macros

This is a full listing of all available template macros in alphabetic order

Return to the main macros page.

-	The dash macro (%-) can be used at the end of a template line and signifies that the next line should be added to the end of the current line (this helps to make templates more legible). If the dash macro is used in the middle of a line, it is replaced by an empty string.
ABnnnPPP	insert a field from the address book. The "nnn" part determines the address that is used to retrieve information from the address book, the "PPP" part is the name of the address book field to be used.  Possible values for the " nnn " part are: TO use the address entry for the TO addressee of the current message OFROM use the address entry for the FROM address of the original message OREPLY use the address entry for the REPLY-TO address of the original message OTO use the address entry for the TO addressee of the original message FROM use the address entry for the FROM address of the current message REPLY use the address entry for the REPLY-TO address of the current message Possible values for the " PPP " part are: Name the full name FirstName the first name LastName the last name MiddleName the middle name Handle the handle (alias) NamePrefix the name prefix (such as "Mr.", "Mrs.", "Dr." etc) NameSuffix the name suffix (such as ", Jr.", ", PhD", etc) Birthday the date of birth Email the primary e-mail address Addr the home street address City the home city name State the home state/province name ZIP the home address ZIP/Postal code Country the home address country name Phone the home phone number Fax the home facsimile number Mobile the mobile phone number Page the personal homepage URL Company the company name Job the job title Dept the department name Office the office number BusAddr the business street address BusCity the business address city name BusState the business address state/province name BusZIP the business address ZIP/Postal code BusCountry the business address Country name BusPhone the business telephone number BusFax the business facsimile number BusPager the business pager number BusPage the business homepage URL Gender the person's gender (0 - undefined, 1 - male, 2 - female) Charset the default character set Memo the Memo contents of the address entry
ABnnnPPP = "text"	insert a field from the address book as above. If there is no matching address book entry or the field requested from the address book is blank, insert text instead
ACCOUNT = "Name"	set the active account to the account with the account name equal to Name
ACCOUNTATTACHDIR	the full path to the account's attachment directory. This macro is useful when used in the parameter of %ATTACHFILE,%INCLUDE and %PUT macros
ACCOUNTDIR	the full path to the account's home directory. This macro is useful when used in the parameter of %ATTACHFILE,%INCLUDE and %PUT macros
ACCOUNTNAME	insert the name of the active account
ADDHEADER(header, text)	add text to the message header, the header parameter should be the RFC name of a header defined in the Message Headers section of the Options|Preferences dialogue
ATTACHFILE = "filepath"	attach a file determined by the filepath
ATTACHMENTS	insert the list of the files attached to the current message
ATTACHVCARD	attach the personal vCard of the active account.
AUTOPGPMIME	set the PGP/MIME option to auto for the current message
BCC = ""	remove all recipients from the BCC field
BCC = "address(es)"	add address(es) to the BCC field
BCCLIST or  BCC	insert the full list of recipient in the BCC address field
BLANK	this macro is used to create a blank template. An empty template will be replaced by the default templates. Use this macro to prevent that
CALCULATE="expression" or CALC="expression"	Calculate mathematical expression. Possible operators are: +,-,*,/,\ (remainder of integer division), ** (power), & (AND), |(OR), ^(XOR),~(NOT), && (logical AND), ||( logical OR), ^^( logical XOR), ! (logical NOT), <, >, ==, <=, >=, ? (ternary operator - (exp0)?(exp1):(exp2) calculates as exp1 if exp0 is not zero and exp2 otherwise). This macro is especially useful in conjunction with Regular Expression macros - i.e. when it is needed to calculate something based on original message data. Note that the numbers must be in a strict form without national thousands separators and the decimal point is "." (a dot)
CAPITAL = "text"	Convert text to title case with a capitalised first letter for every word in the string.
CAPITALFIRST = "text" or UCFIRST = "text"	Convert text to sentence case capitalising the first character of the first word
CC = ""	remove all recipients from the CC field
CC = "address(es)"	add address(es) to the CC field
CCLIST or CC	insert the full list of recipient in the CC address field
CHARSET = "Charset ID"	set the current message character set to the character set corresponding to Charset ID. All available character sets and their IDs are defined in the "Options | XLAT Tables" dialog.
CLEAR	when used in a Quick Template, clears all the previously entered/generated text.
CLIPBOARD	insert the textual contents of the system Clipboard
COMMENT	Copy the text of the comment RFC-822 header into the message body
COMMENT = "text"	add a text comment RFC-822 header to a message
COOKIE	insert a random cookie from the current account's cookies
COOKIE = "filepath"	insert a random cookie from the file defined by the filepath. This allows the use of a virtually unlimited number of cookies
CURSOR	place the caret in the message editor at the position indicated by this macro. This macro does nothing in automatically generated messages
CURSOR="Field ID"	macro for setting focus in a particular editing field before starting message editing, where the Field ID is BODY or TEXT for the message text or RFC name of the header
DATE[="format"]	insert the current date in the long date format (defined by the system's country settings) or using the format specified by the format parameter
DATEEN	insert the current date in "day-of-week, month day,  year" format. The day-of-the-week and the month are full words in English
DATESHORT	insert the current date in the short date format (defined by the system's country settings)
DOW	insert the current day of week
ENCRYPTCOMPLETE	automatically encrypt the current message when it is completed
FOLDERFROMADDR	insert the FROM address of the current folder's Identity properties
FOLDERFROMNAME	insert the FROM name of the current folder's Identity properties
FOLDERNAME	insert the name of the current folder
FOLDERORGANISATION, FOLDERORGANIZATION	insert the Organisation name from the current folder's Identity properties
FOLDERREPLYADDR	insert the REPLY-TO address from the current folder's Identity properties
FOLDERREPLYNAME	insert the REPLY-TO name from the current folder's Identity properties
FROM = "address"	change the default FROM field contents to the given address
FROMADDR	insert the address of the sender
FROMFNAME	insert the first name of the sender
FROMLNAME	insert the last name of the sender
FROMNAME	insert the full name of the sender
FULLSUBJ, FULLSUBJECT	insert the full subject of the message (including Re: and Re[n]: prefixes of replied messages' subjects)
HDRheader	the same as the %HEADER(header) macro, but the header part cannot contain special characters like "-" (dash)
HDRheader="text"	the same as the %ADDHEADER(header, "text") macro, but the header part cannot contain special characters like "-" (dash)
HEADER(header)	insert the text from the current message header field identified by the header parameter. The header parameter is the RFC name of the header defined in the Message Headers  section of the Options|Preferences dialogue
HEADERS	insert the RFC-822 headers of the original message
%IF : "var1" <comparison operator> "var2" : <true> : <false>	Conditional text template insertion macro which works as follows: <comparison operator> may be '=', '>', '<' or '<>' If <var1> is = or > or < or <> (unequal) <var2>, then use the <true> result. If the compare fails, then use the <false> result. Example:  %IF:"%TIME"<"12:00":"morning":%-"%IF:'%TIME'>'17:00':'evening':'afternoon'"  Note that any of the <var1>, <var2>, <true> or <false> elements may be either macros or text strings and macros may be used recursively as well. Comparison of var1 and var2 parameters is case insensitive
IFCASE : "var1" <comparison operator> "var2" : <true> : <false>	the same as th IF  macro, but with case sensitive comparison
IFN : "nvar1" <comparison operator> "nvar2" : <true> : <false>	the same as the IF macro, but the nvar1 and nvar2 parameters are compared as numeric values. Note that if a parameter cannot be converted to a number, the value of the parameter is zero; numbers must be represented in classic form (i.e. without thousand separators and the decimal point character is "." (dot))
INCLUDE = "filepath"	insert the text generated by the template located in the file determined by the filepath
INSERTPGPKEY = "address"	insert the OpenPGP key for the given address from the public key ring. This feature works with the internal OpenPGP implementation only
ISSIGNATURE	when used in a Quick Template, tells the message editor that the Quick Template must be used as a signature. In other words, the text generated by the Quick Template replaces everything after the end-of-message cut mark ("--", dash-dash-space); if the end-of-message line is not detected, it is added to the end of the message followed by the generated text
LANGUAGE = "Language ID"	set the default spell checker language to the language defined by  Language ID. Available Language IDs are: AM - American English EA - Australian English BR - British English CT - Catalan CZ - Czech DA - Danish FI - Finnish FR - French FC - French Canadian GE - German IT - Italian NO - Norwegian (Bokmal) NN - Norwegian (Nynorsk) NL - Dutch PB - Portuguese (Brazil) PT - Portuguese (Iberian) PL - Polish SP - Spanish SW - Swedish RU - Russian HU - Hungarian CSAPI - prefix the ID with this to use CSAPI dictionaries for the specified language.  Example:  %LANGUAGE="CSAPI AM"
LOWER = "text"	Convert text to lower case
MAILDIR	the full path to the program's mail directory. This macro is useful when used in the parameter of %ATTACHFILE,%INCLUDE and %PUT macros
MODIFYONCE(header1, header2, ... )	Prevents multiple modifications of particular headers by re-applying of the same template. A template may be re-applied many times while the textual body of a new message stays unchanged in the message editor. In some cases, it is needed to preserve values of some headers if they were already set or changed by the user (for example, when a template sets the subject using %SUBJECT="..." macro and it is expected that the subject will be modified manually; %MODIFYONCE(Subject) should be used).  Note tha t this macro should be used before any header modification
MSGID	insert the current message's Message ID (taken from the message headers, this does not work for newly created messages, which don't yet have a message ID)
NOENCRYPTCOMPLETE	Message editor only - disables automatic encryption of a message if it was selected by the %SIGNCOMPLETE macro, using the default settings or manually with the menu option
NOPGPMIME or CLEARSIGN	Disable usage of the PGP/MIME format for the current message
NORCPTCONFIRM, NORRQ	disable the Receipt Request flag for the current message
NOREADCONFIRM, NORCR	Disable the Reading Confirmation Request flag for the current message
NOSIGNCOMPLETE	message editor only - disables automatic signing of a message if it was selected by the %SIGNCOMPLETE macro, using the default settings or manually with the menu option
NOSPLIT	disable automatic splitting of the current message if it exceeds the size set in the account's properties
NOUSEPGP	Disable using of OpenPGP for encryption/signing of the current message
NOUSESMIME	Disable using of S/MIME for encryption/signing of the current message
NOWRAPJUSTIFY	Used with the %WRAPPED=" " macro to make the wrapped text justified only to the left edge (no justification performed)
OATTACHMENTS	(replies and forward) Insert the list of the files attached to the original message
OBCCLIST, OBCC	(replies and forward) insert the full list of recipient in the BCC address field of the original message
OCCLIST, OCC	(replies and forward) insert the full list of recipient in the CC address field of the original message
OCHARSET	(replies and forward) insert the name of the original's message charset
OCOMMENT	(replies and forward) insert the text of the Comment header field from the original message
ODATE[="format"]	(replies and forward) insert the date of the original message in the long date format (defined by the system's country settings) or using the format specified by the format parameter
ODATEEN	insert the date of the original message in "day-of-week, month day,  year" format. The day-of-week and month are full words in English
ODATESHORT	(replies and forward) insert the date of the original message in the short date format (defined by the system's country settings)
ODOW	(replies and forward) insert the day of week of the original message
OFROMADDR	(replies and forward) insert the address of the sender of the original message
OFROMFNAME	(replies and forward) insert the first name of the sender of the original message
OFROMLNAME	(replies and forward) insert the last name of the sender of the original message
OFROMNAME	(replies and forward) insert the full name of the sender of the original message
OFULLSUBJ, OFULLSUBJECT	(replies and forward) insert the full subject of the original message
OHEADER="header"	insert the text from the original's message header field identified by the header parameter. The header parameter is the RFC name of the header defined in the Message Headers  section of the Options|Preferences dialogue
OMSGID	insert the original message's Message ID (taken from the message headers)
OORGANIZATION, OORGANISATION	(replies and forward) insert the organisation name from the original message
ORCVDATE[="format"]	(replies and forward) insert the receipt date of the original message in the long date format (defined by the system's country settings) or using the format specified by the format parameter
ORCVDATEEN	(replies and forward) insert the receipt date of the original message in "day-of-week, month day,  year" format. The day-of-week and month are full words in English
ORCVDATESHORT	(replies and forward) insert the receipt date of the original message in the short date format (defined by the system's country settings)
ORCVDOW	(replies and forward) insert the day of week of the original message
ORCVTIME[="format"]	(replies and forward) insert the receipt time of the original message in the short time format (defined by the system's country settings) or using the format specified by the format parameter
ORCVTIMELONG	(replies and forward) insert the receipt time of the original message in the long time format (defined by the system's country settings)
ORCVTIMELONGEN	(replies and forward) insert the receipt time of the original message in "hour:minutes:seconds AM/PM" format
OREPLYADDR	(replies and forward) insert the address of the reply recipient of the original message
OREPLYCOUNTER, ORECOUNT	(replies and forward) insert the numbered reply counter of the original message
OREPLYFNAME	(replies and forward) insert the first name of the reply recipient of the original message
OREPLYLNAME	(replies and forward) insert the last name of the reply recipient of the original message
OREPLYNAME	(replies and forward) insert the full name of the reply recipient of the original message
ORETURNPATH	(replies and forward) insert the full return path of the original message
ORG = "organisation"	redefine the default ORGANISATION field contents with the organisation text
ORGANIZATION, ORGANISATION	insert the organisation name
OSUBJ	(replies and forward) insert the subject of the original message without Re: and Fwd: prefixes
OTEXT	(replies) insert the entire text of the original message. This macro is useful for Regular Expressions macros to ensure that the entire text of a message is used - the TEXT macro inserts only the selected part of text for "Reply ... quoting selected text" and the "Reply without quotation" commands.
OTEXTSIZE	(replies and forward) insert the byte size of the original message
OTIME[="format"]	(replies and forward) insert the time of the original message in the short time format (defined by the system's country settings) or using the format specified by the format parameter
OTIMELONG	(replies and forward) insert the time of the original message in the long time format (defined by the system's country settings)
OTIMELONGEN	(replies and forward) insert the time of the original message in "hour:minutes:seconds AM/PM" format
OTOADDR	(replies and forward) insert the first TO address of the original message
OTOFNAME	(replies and forward) insert the first name of the first TO addressee of the original message
OTOLIST, OTO	(replies and forward) insert the full list of recipient in the TO address field of the original message
OTOLNAME	(replies and forward) insert the last name of the first TO addressee of the original message
OTONAME	(replies and forward) insert the full name of the first TO addressee of the original message
PAGENUMBER	Add page numbers when printing messages (for use in print templates)
PGPMIME	set the PGP/MIME option to "on" for the current message to ensure that the PGP/MIME format is used when the message is signed/encrypted
PRIORITY = "H/N/L"	set the message priority to High/Normal/Low
PROGRAMDIR	the full path to the program directory. This macro is useful when used in the parameter of %ATTACHFILE,%INCLUDE and %PUT macros
PUT = "filepath"	insert the text from the file indicated by the filepath.
QHEADERS	(replies and forward) insert the quoted RFC-822 headers of the original message
QINCLUDE = "Handle" or QT="Handle"	insert the text generated by the Quick Template with the handle which matches he given Handle
QUOTECLIPBOARD, QCLIPBOARD	insert the quoted textual contents of the system Clipboard
QUOTES	(replies and forward) insert the original message text in quote prefixed format
QUOTES = "string"	insert a quote prefixed string
QUOTESTYLE = "expression"	Specify the quotation prefix to be used following execution of this macro.  The expression can be any of the following: NONE -use an empty prefix (the standard) I - use the initials of the sender of the original message (the default) IF - use the first initial of the sender of the original message N - use the full name of the sender of the original message F - use the first name of the sender of the original message L - use the last name of the sender of the original message =text use the "text" as the prefix, e.g. %QUOTESTYLE="=-|"
RCPTCONFIRM	set the Receipt Request flag for the current message
READCONFIRM	set the Reading Confirmation Request flag for the current message
REGEXPBLINDMATCH = "giventext"	same as %REGEXPMATCH (below) except that matching text is not inserted but may be extracted using the %SUBPATT="n" macro
REGEXPMATCH = "giventext "	insert the result of searching in giventext for the Regular Expression previously set by %SETPATTREGEXP="regexp"
REGEXPQUOTES = "regexp"	search for the Regular Expression regexp and insert the result as quoted text
REGEXPTEXT = "regexp"	insert the result of the search for the Regular Expression regexp using the text of the original message as the subject string
REM = "comment"	Add comments to templates
REPLYADDR	Insert the address of the reply recipient
REPLYCOUNTER, RECOUNT	(replies and forward) Insert the numbered reply counter of the current message. This can be used in the %SUBJECT macro: %SUBJECT="%RECOUNT Why don't we change the subject?"
REPLYFNAME	Insert the first name of the reply recipient
REPLYLNAME	insert the last name of the reply recipient
REPLYNAME	insert the full name of the reply recipient
REPLYTO = "address"	replace the default REPLY-TO field contents with the address text
RETURNPATH = "address"	replace the default RETURN-PATH field contents with the address text
SETHEADER("header", "text")	set the message's header field identified by the header parameter to the text overwriting any previously set value of the field. The header parameter is the RFC name of the header defined in the Message Headers  section of the Options|Preferences dialogue
SETPATTREGEXP = "regexp"	set the Regular Expression pattern to the given regexp which will be evaluated with the following %REGEXPMATCH macro text parameter as the subject string
SIGNCOMPLETE	automatically ask to sign the current message when it is completed
SINGLELINE, ONELINE	when used in a Quick Template, makes the output text of the template composed in a single line. This can be useful for templates where long regular expressions used for extracting some text for message fields
SINGLERE	disable reply counting
SPLIT	sets the option to split a message if it exceeds the size specified at the Files and Directories section of the account properties dialogue.
SUBJ	insert the subject of the message without Re: and Fwd: prefixes
SUBJECT = "subject"	set a new subject for the message
SUBPATT = "n"	n is the number of the captured substring to be inserted. Substrings are set by the REGEXPMATCH or REGEXPBLINDMATCH macros. SUBPATT='0' returns the text matching the entire Regular Expression pattern, 1 is the text of the first matching subpattern, 2 - the second matching subpattern,. etc...
TEXT	(replies and forward) insert the text of the original message
TEXT = "nn"	(replies and forward) include the first nn lines of the text only where nn is any valid number.
TEXT="nn L"	includes the first nn lines and any lines with URLs
THEBATSERIALNUMBER	insert The Bat! serial number
THEBATVERSION	insert The Bat! version number
TIME[="format"]	insert the current time in the short time format (defined by the system's country settings) or using the format specified by the format parameter
TIMELONG	insert the current time in the long time format (defined by the system's country settings)
TIMELONGEN	insert the current time in "hour:minutes:seconds AM/PM" format
TO = ""	remove all recipients from the TO field
TO = "address(es)"	add address(es) to the TO field
TOADDR	insert the first TO e-mail address
TOFNAME	insert the first name of the first TO addressee
TOLIST	insert the full list of recipient in the TO address field
TOLNAME	insert the last name of the first TO addressee
TONAME	insert the full name of the first TO addressee
TOTALPAGES	Add the number of pages when printing messages (for use in print templates) - i.e. 1 / 3
TRACKINGNUMBER	random 32-bit number, in hexadecimal which can be used as a tracking number in (for example) support correspondence
UPPER = "text"	convert the text to upper case
USEPGP	enable using of OpenPGP for encryption/signing of the current message
USESMIME	enable using of S/MIME for encryption/signing of the current message
VARname="value" or  %_name="value")	set variables. Use %VARname (or %_name) to insert variable value. Variable name can contain alphabet characters, digits and "_". Variables are especially useful for inserting a the same text (e.g.: result of some calculation or Regular Expression pattern) into various places of message text or headers as well as saving intermediate result of macro combination.
WINDOWSBUILDNUMBER	insert the Windows version build number
WINDOWSCSDVERSION	insert the Windows additional version information
WINDOWSMAJORVERSION	insert the Windows major version number (i.e. the '4' of '4.10')
WINDOWSMINORVERSION	insert the Windows minor version number (i.e. the '10' or '4.10')
WINDOWSPLATFORMNAME	insert the Windows platform name (e.g. Windows 95, Windows NT)
WRAPJUSTIFY	used for the %WRAPPED=" " macro to keep the wrapped text justified by the left and the right edges
WRAPPED = "text"	insert text wrapped as specified by the default editor settings. You can freely use template macros from this list within the text. This macro is very useful when using a lot of macros to generate the text and want that text to be well laid out. For best effect, place the %WRAPPED="text" macro at the beginning of a new line
WRAPPED(limit, "text").	macro for more precise text wrapping. Set value of Limit to the number of symbols were you want auto wrapping to be done

Return to the main macros page.


Address related macros

This is a full alphabetic listing of template macros that apply to or result in email addresses.

Return to the main macros page.

ABnnnPPP	insert a field from the address book. The "nnn" part determines the address that is used to retrieve information from the address book, the "PPP" part is the name of the address book field to be used.  Possible values for the " nnn " part are: TO use the address entry for the TO addressee of the current message OFROM use the address entry for the FROM address of the original message OREPLY use the address entry for the REPLY-TO address of the original message OTO use the address entry for the TO addressee of the original message FROM use the address entry for the FROM address of the current message REPLY use the address entry for the REPLY-TO address of the current message Possible values for the " PPP " part are: Name the full name FirstName the first name LastName the last name MiddleName the middle name Handle the handle (alias) NamePrefix the name prefix (such as "Mr.", "Mrs.", "Dr." etc) NameSuffix the name suffix (such as ", Jr.", ", PhD", etc) Birthday the date of birth Email the primary e-mail address Addr the home street address City the home city name State the home state/province name ZIP the home address ZIP/Postal code Country the home address country name Phone the home phone number Fax the home facsimile number Mobile the mobile phone number Page the personal homepage URL Company the company name Job the job title Dept the department name Office the office number BusAddr the business street address BusCity the business address city name BusState the business address state/province name BusZIP the business address ZIP/Postal code BusCountry the business address Country name BusPhone the business telephone number BusFax the business facsimile number BusPager the business pager number BusPage the business homepage URL Gender the person's gender (0 - undefined, 1 - male, 2 - female) Charset the default character set Memo the Memo contents of the address entry
ABnnnPPP = "text"	insert a field from the address book as above. If there is no matching address book entry or the field requested from the address book is blank, insert text instead
ADDHEADER(header, text)	add text to the message header, the header parameter should be the RFC name of a header defined in the Message Headers section of the Options|Preferences dialogue
BCC = ""	remove all recipients from the BCC field
BCC = "address(es)"	add address(es) to the BCC field
BCCLIST or  BCC	insert the full list of recipient in the BCC address field
CC = ""	remove all recipients from the CC field
CC = "address(es)"	add address(es) to the CC field
CCLIST or CC	insert the full list of recipient in the CC address field
FOLDERFROMADDR	insert the FROM address of the current folder's Identity properties
FOLDERREPLYADDR	insert the REPLY-TO address from the current folder's Identity properties
FROM = "address"	change the default FROM field contents to the given address
FROMADDR	insert the address of the sender
HDRheader	the same as the %HEADER(header) macro, but the header part cannot contain special characters like "-" (dash)
HDRheader="text"	the same as the %ADDHEADER(header, "text") macro, but the header part cannot contain special characters like "-" (dash)
HEADER(header)	insert the text from the current message header field identified by the header parameter. The header parameter is the RFC name of the header defined in the Message Headers  section of the Options|Preferences dialogue
OBCCLIST, OBCC	(replies and forward) insert the full list of recipient in the BCC address field of the original message
OCCLIST, OCC	(replies and forward) insert the full list of recipient in the CC address field of the original message
OFROMADDR	(replies and forward) insert the address of the sender of the original message
OREPLYADDR	(replies and forward) insert the address of the reply recipient of the original message
ORETURNPATH	(replies and forward) insert the full return path of the original message
OTOADDR	(replies and forward) insert the first TO address of the original message
OTOLIST, OTO	(replies and forward) insert the full list of recipient in the TO address field of the original message
REPLYADDR	Insert the address of the reply recipient
REPLYTO = "address"	replace the default REPLY-TO field contents with the address text
RETURNPATH = "address"	replace the default RETURN-PATH field contents with the address text
SETHEADER("header", "text")	set the message's header field identified by the header parameter to the text overwriting any previously set value of the field. The header parameter is the RFC name of the header defined in the Message Headers  section of the Options|Preferences dialogue
TO = ""	remove all recipients from the TO field
TO = "address(es)"	add address(es) to the TO field
TOADDR	insert the first TO e-mail address
TOLIST	insert the full list of recipient in the TO address field

Return to the main macros page.


Name and address macros

This is a full alphabetic listing of template macros that apply to or result in email names and addresses.

This is a full alphabetic listing of template macros that apply to or result in email addresses.

Return to the main macros page.

ABnnnPPP	insert a field from the address book. The "nnn" part determines the address that is used to retrieve information from the address book, the "PPP" part is the name of the address book field to be used.  Possible values for the " nnn " part are: TO use the address entry for the TO addressee of the current message OFROM use the address entry for the FROM address of the original message OREPLY use the address entry for the REPLY-TO address of the original message OTO use the address entry for the TO addressee of the original message FROM use the address entry for the FROM address of the current message REPLY use the address entry for the REPLY-TO address of the current message Possible values for the " PPP " part are: Name the full name FirstName the first name LastName the last name MiddleName the middle name Handle the handle (alias) NamePrefix the name prefix (such as "Mr.", "Mrs.", "Dr." etc) NameSuffix the name suffix (such as ", Jr.", ", PhD", etc) Birthday the date of birth Email the primary e-mail address Addr the home street address City the home city name State the home state/province name ZIP the home address ZIP/Postal code Country the home address country name Phone the home phone number Fax the home facsimile number Mobile the mobile phone number Page the personal homepage URL Company the company name Job the job title Dept the department name Office the office number BusAddr the business street address BusCity the business address city name BusState the business address state/province name BusZIP the business address ZIP/Postal code BusCountry the business address Country name BusPhone the business telephone number BusFax the business facsimile number BusPager the business pager number BusPage the business homepage URL Gender the person's gender (0 - undefined, 1 - male, 2 - female) Charset the default character set Memo the Memo contents of the address entry
ABnnnPPP = "text"	insert a field from the address book as above. If there is no matching address book entry or the field requested from the address book is blank, insert text instead
ADDHEADER(header, text)	add text to the message header, the header parameter should be the RFC name of a header defined in the Message Headers section of the Options|Preferences dialogue
BCC = ""	remove all recipients from the BCC field
BCC = "address(es)"	add address(es) to the BCC field
BCCLIST or  BCC	insert the full list of recipient in the BCC address field
CC = ""	remove all recipients from the CC field
CC = "address(es)"	add address(es) to the CC field
CCLIST or CC	insert the full list of recipient in the CC address field
FOLDERFROMADDR	insert the FROM address of the current folder's Identity properties
FOLDERFROMNAME	insert the FROM name of the current folder's Identity properties
FOLDERNAME	insert the name of the current folder
FOLDERORGANISATION, FOLDERORGANIZATION	insert the Organisation name from the current folder's Identity properties
FOLDERREPLYADDR	insert the REPLY-TO address from the current folder's Identity properties
FOLDERREPLYNAME	insert the REPLY-TO name from the current folder's Identity properties
FROM = "address"	change the default FROM field contents to the given address
FROMADDR	insert the address of the sender
FROMFNAME	insert the first name of the sender
FROMLNAME	insert the last name of the sender
FROMNAME	insert the full name of the sender
HDRheader	the same as the %HEADER(header) macro, but the header part cannot contain special characters like "-" (dash)
HDRheader="text"	the same as the %ADDHEADER(header, "text") macro, but the header part cannot contain special characters like "-" (dash)
HEADER(header)	insert the text from the current message header field identified by the header parameter. The header parameter is the RFC name of the header defined in the Message Headers  section of the Options|Preferences dialogue
OBCCLIST, OBCC	(replies and forward) insert the full list of recipient in the BCC address field of the original message
OCCLIST, OCC	(replies and forward) insert the full list of recipient in the CC address field of the original message
OFROMADDR	(replies and forward) insert the address of the sender of the original message
OFROMFNAME	(replies and forward) insert the first name of the sender of the original message
OFROMLNAME	(replies and forward) insert the last name of the sender of the original message
OFROMNAME	(replies and forward) insert the full name of the sender of the original message
OREPLYADDR	(replies and forward) insert the address of the reply recipient of the original message
OREPLYFNAME	(replies and forward) insert the first name of the reply recipient of the original message
OREPLYLNAME	(replies and forward) insert the last name of the reply recipient of the original message
OREPLYNAME	(replies and forward) insert the full name of the reply recipient of the original message
ORETURNPATH	(replies and forward) insert the full return path of the original message
OTOADDR	(replies and forward) insert the first TO address of the original message
OTOFNAME	(replies and forward) insert the first name of the first TO addressee of the original message
OTOLIST, OTO	(replies and forward) insert the full list of recipient in the TO address field of the original message
OTOLNAME	(replies and forward) insert the last name of the first TO addressee of the original message
OTONAME	(replies and forward) insert the full name of the first TO addressee of the original message
REPLYADDR	Insert the address of the reply recipient
REPLYFNAME	Insert the first name of the reply recipient
REPLYLNAME	insert the last name of the reply recipient
REPLYNAME	insert the full name of the reply recipient
REPLYTO = "address"	replace the default REPLY-TO field contents with the address text
RETURNPATH = "address"	replace the default RETURN-PATH field contents with the address text
SETHEADER("header", "text")	set the message's header field identified by the header parameter to the text overwriting any previously set value of the field. The header parameter is the RFC name of the header defined in the Message Headers  section of the Options|Preferences dialogue
TO = ""	remove all recipients from the TO field
TO = "address(es)"	add address(es) to the TO field
TOADDR	insert the first TO e-mail address
TOFNAME	insert the first name of the first TO addressee
TOLIST	insert the full list of recipient in the TO address field
TOLNAME	insert the last name of the first TO addressee
TONAME	insert the full name of the first TO addressee

Return to the main macros page.


Account data macros

This is a full alphabetic listing of template macros that give access to your account settings.

Return to the main macros page.

ACCOUNT = "Name"	set the active account to the account with the account name equal to Name
ACCOUNTATTACHDIR	the full path to the account's attachment directory. This macro is useful when used in the parameter of %ATTACHFILE,%INCLUDE and %PUT macros
ACCOUNTDIR	the full path to the account's home directory. This macro is useful when used in the parameter of %ATTACHFILE,%INCLUDE and %PUT macros
ACCOUNTNAME	insert the name of the active account
ATTACHVCARD	attach the personal vCard of the active account.
ORG = "organisation"	redefine the default ORGANISATION field contents with the organisation text
ORGANIZATION, ORGANISATION	insert the organisation name

Return to the main macros page.


Information macros

This is a full alphabetic listing of template macros that return system settings.

Return to the main macros page.

OTEXTSIZE	(replies and forward) insert the byte size of the original message
PAGENUMBER	Add page numbers when printing messages (for use in print templates)
THEBATSERIALNUMBER	insert The Bat! serial number
THEBATVERSION	insert The Bat! version number
TOTALPAGES	Add the number of pages when printing messages (for use in print templates) - i.e. 1 / 3
TRACKINGNUMBER	random 32-bit number, in hexadecimal which can be used as a tracking number in (for example) support correspondence
WINDOWSBUILDNUMBER	insert the Windows version build number
WINDOWSCSDVERSION	insert the Windows additional version information
WINDOWSMAJORVERSION	insert the Windows major version number (i.e. the '4' of '4.10')
WINDOWSMINORVERSION	insert the Windows minor version number (i.e. the '10' or '4.10')
WINDOWSPLATFORMNAME	insert the Windows platform name (e.g. Windows 95, Windows NT)

Return to the main macros page.


Date / time macros

This is a full alphabetic listing of template macros that give access to date and time values.

Return to the main macros page.

DATE[="format"]	insert the current date in the long date format (defined by the system's country settings) or using the format specified by the format parameter
DATEEN	insert the current date in "day-of-week, month day,  year" format. The day-of-the-week and the month are full words in English
DATESHORT	insert the current date in the short date format (defined by the system's country settings)
DOW	insert the current day of week
ODATE[="format"]	(replies and forward) insert the date of the original message in the long date format (defined by the system's country settings) or using the format specified by the format parameter
ODATEEN	(replies and forward) insert the date of the original message in "day-of-week, month day,  year" format. The day-of-week and month are full words in English
ODATESHORT	(replies and forward) insert the current date of the original message in the short date format (defined by the system's country settings)
ODOW	(replies and forward) insert the day of week of the original message
ORCVDATE[="format"]	(replies and forward) insert the receipt date of the original message in the long date format (defined by the system's country settings) or using the format specified by the format parameter
ORCVDATEEN	(replies and forward) insert the receipt date of the original message in "day-of-week, month day,  year" format. The day-of-week and month are full words in English
ORCVDATESHORT	(replies and forward) insert the receipt date of the original message in the short date format (defined by the system's country settings)
ORCVDOW	(replies and forward) insert the day of week of the original message
ORCVTIME[="format"]	(replies and forward) insert the receipt time of the original message in the short time format (defined by the system's country settings) or using the format specified by the format parameter
ORCVTIMELONG	(replies and forward) insert the receipt time of the original message in the long time format (defined by the system's country settings)
ORCVTIMELONGEN	(replies and forward) insert the receipt time of the original message in "hour:minutes:seconds AM/PM" format
OTIME[="format"]	(replies and forward) insert the time of the original message in the short time format (defined by the system's country settings) or using the format specified by the format parameter
OTIMELONG	(replies and forward) insert the time of the original message in the long time format (defined by the system's country settings)
OTIMELONGEN	(replies and forward) insert the time of the original message in "hour:minutes:seconds AM/PM" format
TIME[="format"]	insert the current time in the short time format (defined by the system's country settings) or using the format specified by the format parameter
TIMELONG	insert the current time in the long time format (defined by the system's country settings)
TIMELONGEN	insert the current time in "hour:minutes:seconds AM/PM" format

Return to the main macros page.


Privacy macros

This is a full alphabetic listing of template macros that affect and use The Bat!'s privacy support functions for both OpenPGP and S/MIME.

Return to the main macros page.

AUTOPGPMIME	default option for using PGP/MIMEautomatically for OpenPGP signed/encrypted messages, may be used in Quick Templates
ENCRYPTCOMPLETE	automatically encrypt the current message when it is completed
INSERTPGPKEY = "address"	insert the OpenPGP key for the given address from the public key ring. This feature works only with the internal OpenPGP implementation and the built-in PGP v5-8 support
NOENCRYPTCOMPLETE	message editor only - disables automatic encryption of a message if it was selected by the %SIGNCOMPLETE macro, using the default settings or manually with the menu option
NOPGPMIME	disable PGP/MIME for the current message
NOSIGNCOMPLETE	message editor only - disables automatic signing of a message if it was selected by the %SIGNCOMPLETE macro, using the default settings or manually with the menu option
NOUSEPGP	disable using of OpenPGP for encryption/signing of the current message
NOUSESMIME	disable using of S/MIME for encryption/signing of the current message
PGPMIME	always use PGP/MIME for the message (some systems may require PGP/MIME because they do not support the ASCII-armoured format)
SIGNCOMPLETE	message editor only - automatically ask to sign the current message when it is completed
USEPGP	enable using of OpenPGP for encryption/signing of the current message
USESIME	enable using of S/MIME for encryption/signing of the current message

Return to the main macros page.


Configuration macros

This is a full alphabetic listing of template macros that return affect or return configuration options.

Return to the main macros page.

ACCOUNT = "Name"	set the active account to the account with the account name equal to Name
ACCOUNTATTACHDIR	the full path to the account's attachment directory. This macro is useful when used in the parameter of %ATTACHFILE,%INCLUDE and %PUT macros
ACCOUNTDIR	the full path to the account's home directory. This macro is useful when used in the parameter of %ATTACHFILE,%INCLUDE and %PUT macros
ACCOUNTNAME	insert the name of the active account
ENCRYPTCOMPLETE	automatically encrypt the current message when it is completed
ISSIGNATURE	when used in a Quick Template, tells the message editor that the Quick Template must be used as a signature. In other words, the text generated by the Quick Template replaces everything after the end-of-message cut mark ("--", dash-dash-space); if the end-of-message line is not detected, it is added to the end of the message followed by the generated text
LANGUAGE = "Language ID"	Set the default spell checker language to the language defined by the Language ID. Available Language IDs are: AM - American English EA - Australian English BR - British English CT - Catalan CZ - Czech DA - Danish FI - Finnish FR - French FC - French Canadian GE - German IT - Italian NO - Norwegian (Bokmal) NN - Norwegian (Nynorsk) NL - Dutch PB - Portuguese (Brazil) PT - Portuguese (Iberian) PL - Polish SP - Spanish SW - Swedish RU - Russian HU - Hungarian CSAPI - prefix the ID with this to use CSAPI dictionaries for the specified language. Example:  %LANGUAGE="CSAPI AM"
MAILDIR	the full path to the program's mail directory. This macro is useful when used in the parameter of %ATTACHFILE,%INCLUDE and %PUT macros
MODIFYONCE(header1, header2, ... )	Prevents multiple modifications of particular headers by re-applying of the same template. A template may be re-applied many times while the textual body of a new message stays unchanged in the message editor. In some cases, it is needed to preserve values of some headers if they were already set or changed by the user (for example, when a template sets the subject using %SUBJECT="..." macro and it is expected that the subject will be modified manually; %MODIFYONCE(Subject) should be used).  Note that this macro should be used before any header modification
NOENCRYPTCOMPLETE	message editor only - disables automatic encryption of a message if it was selected by the %SIGNCOMPLETE macro, using the default settings or manually with the menu option
NORCPTCONFIRM	disable the Receipt Request flag for the current message
NOREADCONFIRM	disable the Reading Confirmation Request flag for the current message
NOSIGNCOMPLETE	message editor only - disables automatic signing of a message if it was selected by the %SIGNCOMPLETE macro, using the default settings or manually with the menu option
NOSPLIT	disable automatic splitting of the current message if it exceeds the size set in the account's properties
NOUSEPGP	disable using of OpenPGP for encryption/signing of the current message
NOUSESMIME	disable using of S/MIME for encryption/signing of the current message
NOWRAPJUSTIFY	used with the %WRAPPED=" " macro to make the wrapped text justified only to the left edge (no justification performed)
PRIORITY = "H/N/L"	set the message priority to High/Normal/Low
PROGRAMDIR	the full path to the program directory. This macro is useful when used in the parameter of %ATTACHFILE,%INCLUDE and %PUT macros
QUOTESTYLE = "expression"	specify the quotation prefix to be used following execution of this macro.  The expression can be any of the following: NONE use an empty prefix (the standard) I use the initials of the sender of the original message (the default) IF use the first initial of the sender of the original message N use the full name of the sender of the original message F use the first name of the sender of the original message L use the last name of the sender of the original message =text use the "text" as the prefix, e.g. %QUOTESTYLE="=-|"
RCPTCONFIRM	set the Receipt Request flag for the current message
READCONFIRM	set the Reading Confirmation Request flag for the current message
REPLYCOUNTER, RECOUNT	Insert the numbered reply counter of the current message. This can be used in the %SUBJECT macro: %SUBJECT="%RECOUNT Why don't we change the subject?"
SINGLERE	Disable reply counting
SPLIT	sets the option to split a message if it exceeds the size specified at the Files and Directories section of the account properties dialogue.
USEPGP	enable using of OpenPGP for encryption/signing of the current message
USESMIME	enable using of S/MIME for encryption/signing of the current message

Return to the main macros page.


Message header macros

This is a full alphabetic listing of template macros that return or affect your message headers.

Return to the main macros page.

ADDHEADER(header, text)	add text to the message header, the header parameter should be the RFC name of a header defined in the Message Headers section of the Options|Preferences dialogue
COMMENT	Copy the text of the comment RFC-822 header into the message body
COMMENT  = "text"	add a text comment RFC-822 header to a message
FULLSUBJ	insert the full subject of the message
HDRheader	the same as the %HEADER(header) macro, but the header part cannot contain special characters like "-" (dash)
HDRheader="text"	the same as the %ADDHEADER(header, "text") macro, but the header part cannot contain special characters like "-" (dash)
HEADER(header)	insert the text from the current message header field identified by the header parameter. The header parameter is the RFC name of the header defined in the Message Headers  section of the Options|Preferences dialogue
HEADERS	insert the RFC-822 headers of the original message
MSGID	insert the current message's Message ID (taken from the message headers, this does not work for newly created messages, which don't yet have a message ID)
OFULLSUBJ	(replies and forward) insert the full subject of the original message
OHEADER(header)	insert the text from the original's message header field identified by the header parameter. The header parameter is the RFC name of the header defined in the Message Headers  section of the Options|Preferences dialogue
OMSGID	(replies and forward) insert the original message's Message ID (taken from the message headers)
OORGANIZATION, OORGANISATION	(replies and forward) insert the organisation name from the original message
ORETURNPATH	(replies and forward) insert the full return path of the original message
ORG = "organisation"	redefine the default ORGANISATION field contents with the organisation text
ORGANIZATION, ORGANISATION	insert the organisation name
OSUBJ	(replies and forward) insert the subject of the original message without Re: and Fwd: prefixes
PRIORITY = "H/N/L"	set the message priority to High/Normal/Low
QHEADERS	(replies and forward) insert the quoted RFC-822 headers of the original message
REPLYCOUNTER, RECOUNT	Insert the numbered reply counter of the current message. This can be used in the %SUBJECT macro: %SUBJECT="%RECOUNT Why don't we change the subject?"
SETHEADER("header", "text")	set the message's header field identified by the header parameter to the text overwriting any previously set value of the field. The header parameter is the RFC name of the header defined in the Message Headers  section of the Options|Preferences dialogue
SINGLERE	disable reply counting
SUBJ	insert the subject of the message without Re: and Fwd: prefixes
SUBJECT = "subject"	set a new subject for the message

Return to the main macros page.


Message content macros

This is a full alphabetic listing of template macros that give access to or change your message content.

Return to the main macros page.

ATTACHFILE = "filepath"	attach a file determined by the filepath
ATTACHMENTS	insert the list of the files attached to the current message
ATTACHVCARD	attach the personal vCard of the active account.
AUTOPGPMIME	set the PGP/MIME option to auto for the current message
BLANK	this macro is used to create a blank template. An empty template will be replaced by the default templates. Use this macro to prevent that
CHARSET = "Charset ID"	set the current message character set to the character set corresponding to Charset ID. All available character sets and their IDs are defined in the "Options | XLAT Tables" dialog.
CLEAR	when used in a Quick Template, clears all the previously entered/generated text.
CLIPBOARD	insert the textual contents of the system Clipboard
COMMENT	Copy the text of the comment RFC-822 header into the message body
COOKIE	insert a random cookie from the current account's cookies
COOKIE = "filepath"	insert a random cookie from the file defined by the filepath. This allows the use of a virtually unlimited number of cookies
CURSOR	place the caret in the message editor at the position indicated by this macro. This macro does nothing in automatically generated messages
CURSOR="Field ID"	macro for setting focus in a particular editing field before starting message editing, where the Field ID is BODY or TEXT for the message text or RFC name of the header
ENCRYPTCOMPLETE	automatically encrypt the current message when it is completed
INCLUDE = "filepath"	insert the text generated by the template located in the file determined by the filepath
INSERTPGPKEY = "address"	insert the OpenPGP key for the given address from the public key ring. This feature works with the internal OpenPGP implementation only
ISSIGNATURE	when used in a Quick Template, tells the message editor that the Quick Template must be used as a signature. In other words, the text generated by the Quick Template replaces everything after the end-of-message cut mark ("--", dash-dash-space); if the end-of-message line is not detected, it is added to the end of the message followed by the generated text
LANGUAGE = "Language ID"	set the default spell checker language to the language defined by Language ID. Available Language IDs are: AM - American English EA - Australian English BR - British English CT - Catalan CZ - Czech DA - Danish FI - Finnish FR - French FC - French Canadian GE - German IT - Italian NO - Norwegian (Bokmal) NN - Norwegian (Nynorsk) NL - Dutch PB - Portuguese (Brazil) PT - Portuguese (Iberian) PL - Polish SP - Spanish SW - Swedish RU - Russian HU - Hungarian CSAPI - prefix the ID with this to use CSAPI dictionaries for the specified language.  Example:  %LANGUAGE="CSAPI AM"
NOENCRYPTCOMPLETE	message editor only - disables automatic encryption of a message if it was selected by the %SIGNCOMPLETE macro, using the default settings or manually with the menu option
NOPGPMIME or CLEARSIGN	Disable usage of the PGP/MIME format for the current message
NORCPTCONFIRM	disable the Receipt Request flag for the current message
NOREADCONFIRM	disable the Reading Confirmation Request flag for the current message
NOSIGNCOMPLETE	message editor only - disables automatic signing of a message if it was selected by the %SIGNCOMPLETE macro, using the default settings or manually with the menu option
NOUSEPGP	disable using of OpenPGP for encryption/signing of the current message
NOUSESMIME	disable using of S/MIME for encryption/signing of the current message
NOWRAPJUSTIFY	used with the %WRAPPED=" " macro to make the wrapped text justified only to the left edge (no justification performed)
OATTACHMENTS	(replies and forward) insert the list of the files attached to the original message
OTEXT
PGPMIME	set the PGP/MIME option to "on" for the current message to ensure that the PGP/MIME format is used when the message is signed/encrypted
PUT = "filepath"	insert the text from the file indicated by the filepath.
QHEADERS	insert the quoted RFC-822 headers of the original message
QINCLUDE = "Handle" or  QT= "Handle"	insert the text generated by the Quick Template with the handle which matches he given Handle
QUOTECLIPBOARD	insert the quoted textual contents of the system Clipboard
QUOTES	(replies and forward) insert the original message text in quote prefixed format
QUOTES = "string"	insert a quote prefixed string
QUOTESTYLE = "expression"	Specify the quotation prefix to be used following execution of this macro.  The expression can be any of the following: NONE -use an empty prefix (the standard) I - use the initials of the sender of the original message (the default) IF - use the first initial of the sender of the original message N - use the full name of the sender of the original message F - use the first name of the sender of the original message L - use the last name of the sender of the original message =text use the "text" as the prefix, e.g. %QUOTESTYLE="=-|"
RCPTCONFIRM	set the Receipt Request flag for the current message
READCONFIRM	set the Reading Confirmation Request flag for the current message
REGEXPBLINDMATCH = "giventext"	same as %REGEXPMATCH (below) except that matching text is not inserted but may be extracted using the %SUBPATT="n" macro
REGEXPMATCH = "giventext "	insert the result of searching in giventext for the Regular Expression previously set by %SETPATTREGEXP="regexp"
REGEXPQUOTES = "regexp"	search for the Regular Expression regexp and insert the result as quoted text
REGEXPTEXT = "regexp"	insert the result of the search for the Regular Expression regexp using the text of the original message as the subject string
SETPATTREGEXP = "regexp"	set the Regular Expression pattern to the given regexp which will be evaluated with the following %REGEXPMATCH macro text parameter as the subject string
SIGNCOMPLETE	automatically ask to sign the current message when it is completed
SINGLELINE, ONELINE	when used in a Quick Template, makes the output text of the template composed in a single line. This can be useful for templates where long regular expressions used for extracting some text for message fields
SUBPATT = "n"	n is the number of the captured substring to be inserted. Substrings are set by the REGEXPMATCH or REGEXPBLINDMATCH macros. SUBPATT='0' returns the text matching the entire Regular Expression pattern, 1 is the text of the first matching subpattern, 2 - the second matching subpattern,. etc...
TEXT	(replies and forward) insert the text of the original message
TEXT = "nn"	(replies and forward) include the first nn lines of the text only where nn is any valid number.
TEXT="nn L"	insert the first nn lines and any lines with URLs
USEPGP	enable using of OpenPGP for encryption/signing of the current message
USESMIME	enable using of S/MIME for encryption/signing of the current message
WRAPJUSTIFY	used for the %WRAPPED=" " macro to keep the wrapped text justified by the left and the right edges
WRAPPED = "text"	insert text wrapped as specified by the default editor settings. You can freely use template macros from this list within the text. This macro is very useful when using a lot of macros to generate the text and want that text to be well laid out. For best effect, place the %WRAPPED="text" macro at the beginning of a new line
WRAPPED(limit, "text")	macro for more precise text wrapping. Set value of Limit to the number of symbols were you want auto wrapping to be done.

Return to the main macros page.


Regular expression and programming macros

This is a full alphabetic listing of template macros that provide enhanced logical manipulation and decision making capabilities to your templates.

Return to the main macros page.

-	The dash macro (%-) can be used at the end of a template line and signifies that the next line should be added to the end of the current line (this helps to make templates more legible). If the dash macro is used in the middle of a line, it is replaced by an empty string.
CALCULATE="expression" or CALC="expression"	Calculate mathematical expression. Possible operators are: +,-,*,/,\ (remainder of integer division), ** (power), & (AND), |(OR), ^(XOR),~(NOT), && (logical AND), ||( logical OR), ^^( logical XOR), ! (logical NOT), <, >, ==, <=, >=, ? (ternary operator - (exp0)?(exp1):(exp2) calculates as exp1 if exp0 is not zero and exp2 otherwise). This macro is especially useful in conjunction with Regular Expression macros - i.e. when it is needed to calculate something based on original message data. Note that the numbers must be in a strict form without national thousands separators and the decimal point is "." (a dot)
CAPITAL = "text"	Convert text to title case with a capitalised first letter for every word in the string.
CAPITALFIRST = "text" UCFIRST = "text"	Convert text to sentence case capitalising the first character of the first word
%IF : "var1" <comparison operator> "var2" : <true> : <false>	Conditional text template insertion macro which works as follows: <comparison operator> may be '=', '>', '<' or '<>' If <var1> is = or > or < or <> (unequal) <var2>, then use the <true> result. If the compare fails, then use the <false> result. Example:  %IF:"%TIME"<"12:00":"morning":%-"%IF:'%TIME'>'17:00':'evening':'afternoon'"  Note that any of the <var1>, <var2>, <true> or <false> elements may be either macros or text strings and macros may be used recursively as well. Comparison of var1 and var2 parameters is case insensitive
IFCASE : "var1" <comparison operator> "var2" : <true> : <false>	the same as th IF  macro, but with case sensitive comparison
IFN : "nvar1" <comparison operator> "nvar2" : <true> : <false>	the same as the IF macro, but the nvar1 and nvar2 parameters are compared as numeric values. Note that if a parameter cannot be converted to a number, the value of the parameter is zero; numbers must be represented in classic form (i.e. without thousand separators and the decimal point character is "." (dot))
INCLUDE = "filepath"	insert the text generated by the template located in the file determined by the filepath
LOWER = "text"	Convert text to lower case
QINCLUDE = "Handle"	insert the text generated by the Quick Template with the handle which matches he given Handle
REGEXPBLINDMATCH = "giventext"	same as %REGEXPMATCH (below) except that matching text is not inserted but may be extracted using the %SUBPATT="n" macro
REGEXPMATCH = "giventext "	insert the result of searching in giventext for the Regular Expression previously set by %SETPATTREGEXP="regexp"
REGEXPQUOTES = "regexp"	search for the Regular Expression regexp and insert the result as quoted text
REGEXPTEXT = "regexp"	insert the result of the search for the Regular Expression regexp using the text of the original message as the subject string
REM = "comment"	Add comments to templates
SUBPATT = "n"	n is the number of the captured substring to be inserted. Substrings are set by the REGEXPMATCH or REGEXPBLINDMATCH macros. SUBPATT='0' returns the text matching the entire Regular Expression pattern, 1 is the text of the first matching subpattern, 2 - the second matching subpattern,. etc...
TOTALPAGES	insert the total number of printable pages
TRACKINGNUMBER	random 32-bit number, in hexadecimal which can be used as a tracking number in (for example) support correspondence
UPPER="text"	convert the text to upper case
VARname="value" or  %_name="value"	set variables, use %VARname (or %_name) to insert variable value. Variable name can contain alphabet characters, digits and "_". Variables are especially useful for inserting a the same text (e.g.: result of some calculation or Regular Expression pattern) into various places of message text or headers as well as saving intermediate result of macro combination

Return to the main macros page.


The Address Book
Address Book

The Address Book provides you with an easy way to maintain the list of contacts you have. It is possible to create groups dedicated to a particular classification or for use as a mailing list. There are many ways to add a record to the Address Book. Here are the top four ways of doing this manually:

1. When you see an e-mail address highlighted while viewing a message, click the right mouse button and then choose Add to Address Book command in the pop-up menu.

2. When you are filling in the "To:" field in the message editor, press the button with an arrow on it - the e-mail addresses contained in the "To:" field will be added to Address Book.

3. When using the message list, there is an Add to address Book command in the "Specials" sub menu in the local pop-up menu. This is available for both Sender and Recipient addresses. You can also use the shortcut keys to add Sender (<Ctrl+W>) or Recipient (<Shift+Ctrl+W>) to the address book.

4. Using the New address entry menu command (or the toolbar icon) in Address Book.

It is possible to sort Address Book entries automatically using the "Edit | Sort" sub-menu of the Address book or manually using drag-and-drop operations.

You can also use address book Import and Export functions to interchange lists of addresses between different systems and different formats.

Addresses can also be added to the address book using the Sorting Office Filters to automatically add sender and recipient addresses to the address book during the filter process. See the 'Add addresses to Address Book' section of the Sorting Office 'Filtering actions' topic for more details.

The addresses in your address book can be organised into Address Book Groups. Each group can have its own specific templates, allowing you to customise how message sent to members of that group will appear.


Address Groups
Address Book Groups

The addresses in your address book can be organised into Address Book Groups. Each group can have its own specific templates, allowing you to customise how message sent to members of that group will appear.

Any entry in the Address Book can belong to any number of groups.

There are a number of different ways to add an address to a group.

•	Open the properties of the entry in the address book. To the right of the "Groups" field of the main properties panel is a [image] button. Press this. You will be presented with a checklist of available groups. Put ticks in the boxes against the groups you want the name to belong to.

•	You can just type the group handles into the "Groups" field separated by '+' signs.

•	You can also use <Ctrl+Drag/Drop> to copy names into other groups from the main list.

Note the Group property which says "Hide items unless explicitly selected". This makes names not appear in the root when they are in that group. By default this option is turned on, so don't be alarmed when addresses you have added to groups disappear from the main list.

If you want to write to every member of an address book group then you can use the Mass Mailing feature. This will create a personal mail to every member of the group. Alternatively you can type "Handle <list>" into the address field of a message, where "Handle" is the handle of the Address book group. The Bat! will resolve this at the point of sending and will create an identical message to every member of the group. The advantage of Mass mailing over Group mailing is that Mass mailing will create an individual mail to every member of the group, resolving personalising touches at the point of creation. Group mailing will not do this.

See also: Using The Bat! as a Mailing List


Favourites
Address Book Favourites

Within the Address Book, the entry list includes a checkbox in a column marked "Favourites". When the box is ticked, the address book entry becomes one of your favourites.

 You can easily select one of your Favourite addresses when you want to start a new message by clicking on the small down arrow next to the new message icon. This will drop down a menu, which is filled with a list of your favourite addresses from your address book.

You can also access the favourites menu from the new message editor by right clicking on any address ("To:", "CC:" or "BCC:") field.

Address book favourites make it very simple to address messages to the people that you write to more frequently.


Importing addresses
Importing Addresses into the Address Book

The Bat! can directly import addresses from address books in the following formats:

•	The Bat! Address book

•	Eudora Address book (in .TXT form)

•	Pegasus Tag File (in .TXT form)

The Bat! address book can also import raw address information from any client that can export the information to:

•	LDIF File

•	Vcard

•	Comma Separated File

•	Tab Separated File

•	".INI" file format

From the address book menu, select the "File | Import from" option and choose the import method you want to use.

See also Exporting addresses from the address book.


Exporting Addresses
Exporting Addresses from the Address Book

The Bat! can directly export addresses to the following formats:

•	LDIF File

•	Vcard

•	Comma Separated File

•	Tab Separated File

•	".INI" file format

These export formats are available from the "File | Export to" menu option.

By using the "File | Export to | Export selection" menu option and choosing the appropriate file type from the drop down in the "Export address book" file save dialog box, you can export a selected batch of address book entries instead of all entries.

See also Importing addresses from the address book.


Folder
Folders

Folders are the place where messages are kept. There are two types of folder in The Bat!: standard (or system) and user-defined (or custom). The general purpose of folders is for the classification of messages so that you may easily find messages related to a particular topic.

Each account has its own folder hierarchy. Folders can be named and nested depending on their use, but any account has four standard folders:

Inbox	the default folder for incoming mail
Outbox	the folder for outgoing messages
Sent	the default folder for sent messages
Trash	Wastebasket - all deleted messages from other folders are stored here, when a message is deleted from the Trash folder, it will be erased permanently (unless you keep a copy on the server).

Standard folders cannot be deleted. They can be moved within the hierarchy but only at the root level.

With sorting rules

(Account | Sorting Office/Filters), you can determine in which folder messages should be placed after they have been received, sent, read or replied to.

For example, you may have a contact from whom you often receive messages and you might want to keep track of mails from him/her. You can create a folder with a relevant name, which gives you a clue that the folder holds messages from this contact (his/her name, for instance). You can then create a sorting rule in the Incoming Mail group with the person's e-mail address or name as a signal string, located in the "sender" information for the sorting rule. Once done, all incoming messages from this contact will be moved into the folder that you have created as soon as they arrive.

A User-defined folder may also have its own templates for new messages, replies to messages from this folder and for message forwarding and confirmation, as well as sounds for notification about new messages. You can also define an "identity" for yourself when writing messages while this folder is selected. The "identity" settings allow you to override the "From" and "Reply-to" information that appears in the General Account Details.

It is possible to move and copy messages from one folder to another by a simple drag-and-drop operation: if no keys are pressed while the message is being dragged, a Move operation is performed, if the <Ctrl> key is held down while dragging, the message is copied.

A folder can have sub-folders.

To re-position a folder within the account's hierarchy, press and hold the Alt key and then use drag-and-drop to move the desired folder. This will move a folder next to the folder onto which it is dropped in the account folder tree. To drop a folder into another folder and make it appear as a sub-folder, use <Ctrl+Alt> while dragging the folder.


Folder settings

Name - the name of the folder as it appears in the folder hierarchy of the account. For The Bat!, the name is also used as the default name for the folder's message base sub-directory. This is not the case in SecureBat!, where the folder names are encoded.

Directory - the directory where the folder's message base file (MESSAGES.TBB or MESSAGES.EBB for SecureBat!) will be stored. If it is set to <default>, make sure that the folder's name does not contain characters disallowed by the file system ("\", "/", "+", "|", "<", ">", ":"), otherwise you will be asked either to rename the folder or to change the folder's directory.

Show unread messages on MailTicker ™ - unread messages in this folder appear on the MailTicker ™.

Use the account default column settings - the column settings in the message list view for this folder conform to the account defaults. This also means that any changes to this folder's column settings will be applied to any other such "defaulted" folders. N.B. There is no default folder per-se. Any folder which is selected to "Use the account default column settings" becomes the "master" for the values to be used.

Maximum number of stored messages- the maximum amount of messages The Bat! is allowed to keep in the message base. If the number of messages exceeds this value, earlier messages will be automatically deleted from the message base by the Purge command.

Keep messages in the base for n days - The maximum age of a message allowed in the message base. If a message is older than this, it will be automatically deleted from the message base by the Purge command.

On Exit actions

Remove old messages - purge messages using the values specified in the above settings. The "Purge messages" operation will mark purge messages as deleted but not remove them permanently from the message base file.

Compress the folder - compress the folder's message base file. The "Compress" function permanently removes any messages from the message base that were previously marked as deleted. Use of the "Compress" function will reduce the amount of disk space used by your message base files.

Identity

It is possible to re-define the identity settings (i.e. default "From:" and "Reply-To:" fields' contents) for a particular folder using the settings located on the "Identity" page of the Folder Properties dialog box. You can also change your "Identity" on-the-fly using custom templates and macros.

Deletion settings

You can use folder-specific setting for the deletion of your messages. For example when you are deleting from the Junk folder you might want permanently to delete messages.

Use the following options when you are deleting your messages using <Del> or the toolbar button:

Move messages to the Trash folder is the default option that if checked moves your messages to the Trash folder.

Mark as deleted, do not use the Trash folder deletes messages from the folder without moving them to the Trash folder.

Move to the specified folder you can choose an alternative folder to be used as Trash when messages are deleted.

The same options are available for alternative deletion. Use <Shift+Del> or the toolbar button for Alternative delete.

Compress emptied folder automatically use this option to compress the folder automatically when the deletion has been done.

See also:

Templates

New mail notification (Sound).


Virtual Folders

Virtual Folders is a special kind of folders that allow you to have list of messages from designated sets of folders grouped by a specific criteria. Virtual Folders do not keep copies of messages in their database - they only keep references to the original messages kept in non-virtual folders. This means that whenever you change a message from a virtual folder, the changes will apply to the original message residing in a non-virtual folders. The same applies for deletion.

There are two ways to create a Virtual Folder:

1.	Use the "Folder|New (Common) Virtual Folder" menu command, then specify the condition and folder set at the "Filter" page.

2.	Search messages using the Message Finder (the "Tools|Search..." menu command), then click the "Virtual Folder" button to create a Virtual Folder based on the condition and scope you were using to find messages.

Here is a short list of examples of how Virtual Folders can be used:

•	Keeping track of unread messages on specific set of folders - e.g. folders related to some projects important to you.

•	Collecting flagged messages from different folders - usually, flag is used for marking important messages; having a virtual folder that collects all your flagged messages would save you a lot of time

•	When Colour Groups are used to specify state of message processing, it would be a good idea to create a Virtual Folder for each Colour Group.


Sorting Office - general information
Sorting Office (Message Filters)

The Bat! V3 introduces a completely new filtering system designed to help you deal with the ever increasing amount of messages with minimum of effort. It automates many tasks that you had to carry out manually. Now it has got a new flow chart style front end, it became more logical and easy for understanding.

The Sorting Office is implemented in The Bat! for auto-classification of incoming, outgoing(sent), read and replied mail. Each of the above mentioned message streams can be sorted into specific folders, according to this set of rules.

Each rule is determined by its name, the set of possible source folder (for incoming mail it is always Inbox, for outgoing - Outbox and this cannot be changed),  filter and defined actions. To create a new rule, open the "Account | Sorting Office/Filters" dialog (<Shift+Ctrl+S>), select the desired rule set (depending on what type of messages you want to classify) in the explorer, and press the New button.

The Bat! also has an easy way to create filters. Use the "Specials | Create filter" menu option (<Shift+Ctrl+F>) to use the quick filter creation dialog box. This will allow you to select one or all of the Sender, Subject or Recipient information from the current message to create the filter. You can choose whether the filter should apply to incoming, outgoing, read or replied messages and which folder messages should be filtered to. There is also an option to "Override existing filters". Use this flag to place the new filter at the top of the list of filters. Finally, you can choose the "OK" button to simply create the filter and move on or the "Edit" button if you want to open the Sorting office and add filtering actions or options.

The order of filters is important since The Bat! processes filters from the top down. If the first filter triggers and does not allow further processing with other filters then the remaining filters will be "resting".

By the way, filters that allow further processing are blue coloured in the filter tree.

Sub-filters can play an important role as well. They serve as addendum to the main filter, which is based on certain conditions. Let's take an example in order to see its benefits: you receive messages from your friends and want to keep them in a separate folder. Everything goes as planned, but at some point you come to the conclusion that it would be nice to store messages from the closest friend in another folder or simply apply a certain colour to those messages. Your next step? Creating a separate filter or a sub-filter? The latter one is the best way out for many reasons, one of them – certain filters are grouped and the main filter tree does not grow to large and confusing.

Related topics:

Filer Editor

Filtering actions

Filtering options.

Using special syntax in signal strings

Using The Bat! as a Mailing List Server

Regular Expressions

Selective Downloads

Dealing with UCE (spam)


Filter editor

A filter consists of conditions and condition blocks joined by a logical operator; it is a condition block by itself.

A condition is a combination of selectors, edit controls and combo boxes and occupies one line in the block. A selector is identified by a little triangle, click the selector to see the menu of its options or press the first letter of the option's name, pressing the same letter again will cycle through available options with names starting with the same letter (the space key can be used for cycling through all options).

How to edit a filter?

To add a condition:

1. Click the "Add condition" button or press the Insert key when another condition is selected.

2. Choose the condition type using the condition specifier's selector (the first part of the condition displayed in bold).

3. Specify the rest of the condition.

To add a condition block, click the "Add Block" button or press Ctrl+Ins when a condition is selected.

To delete a condition, click the "Delete" button or press Ctrl+Delete when the condition is selected.

To delete a block, select the logical operator right above the block, then  click the "Delete" button or press Ctrl+Delete.

How conditions are tested

Conditions are tested in groups joined by the AND and AND NOT logical operations in order from top to bottom.   If a condition in such a group is not satisfied, the conditions in the group below the unsatisifed condition are not tested.

Tip: place "resource heavy" conditions (such as regular expression evaluation, search in message body and address book) after "easier ones" if they are joined by AND or AND NOT - this may increase speed of testing significantly.

Using Regular Expressions for text search

To use Regular Expressions in conditions with text search, use the "match" options (match, does not match, match any of and matches all as RegExp)


Filtering actions

Each filtering rule has its own set of actions, which will be executed whenever a message satisfying the filtering condition appears in the source folder. Actions can be defined at the Actions page of the Sorting Office configuration dialog - to add an action, select the desired action from the list of available actions and click the Add button.

The uppermost action is executed first, then the rest. This may be important when for example you want to create a formatted message (not preserving the original headers) in certain folder and then export the message. In this case, depending on the actions hierarchy, you will get different messages exported i.e. one containing RFC headers and the other not. And if you also define the delete the message action and place it before the export actions what you will get is a message deleted and not exported. Whereas if you do vice versa (first export, then delete) you will get a nice job done.

Let's take a look at the most commonly used filtering actions:

Move the message to folder – the message is moved from the Inbox folder to a specified one. This may be useful if you want to store messages from a particular sender(s) (either friend(s) or newsletters) in a separate folder.

Copy the message to folder - duplicate the message in additional folder. This may be useful if you want another user to read messages of specific type. You can optionally mark the copy as Read.

Mark message as read - can be used for incoming messages because messages filtered by other rule sets are supposed to be marked as read already. Or for example if you receive reading  or receipt confirmations from people you send messages to and there is no need to read them, but still you would like to preserve them.

Set message colour - is used to change which user defined Message list colour group the message belongs to.

Send automatic reply - automatically generate a reply message to the sender's address using a template and the message's text as the text for quotation.

Create reading confirmation (forced) - automatically generate a message to the sender of the message (or the reply address) using a standard reading confirmation template.

Forward the message - forward the message to a specific address(es). Options allow you to use the entire message including headers (kludges) as the quoted text, send the message as an attachment (in a MIME envelope) and to skip sending of attachments. The forwarding template of the target folder is used for generating the forwarded message.

Play a sound - you can get The Bat! to play a sound in response to a filter - either a specific WAV file or a system sound. You can put time restrictions on when this sound should be played.


Filtering options

Each filtering rule has a set of options which can be set to govern how it works.

This filter is active – here you can define if the filter is on or off. This is useful when you need to temporary suspend a particular filter but do not want to delete it. What you have is a nice solution.

Use this filter for manual re-filtering only – the filter will only work on manual re-filtering, it will not be taken into account for automatic filtering of the messages.

Continue processing with other filters - set this switch if you want to continue processing the next filter once this filter has been triggered. Normally, if The Bat! finds a match it will stop the filtering process at that point. This switch is often used in conjunction with a non-moving filter - one which specifies the same source folder as destination folder. For instance, such a filter can be used to set the Colour Group of a message before moving it to another folder. See Filtering Actions for more information on actions.

Execute action set of this rule by pressing the Hot Key - You can define a hot key which, when pressed, will invoke this rule on the currently selected message. There is a check box within this option to specify whether or not the selected message should be checked against this rule before the actions are performed.

Send generated messages - there are three options here - to send any generated messages either immediately or to leave them queued in the outbox for sending at the next transmission cycle. The latter option is especially useful if you may need to cast an eye over generated messages before they are sent. The remaining options permit to send the messages according to the account settings.


Using The Bat! as a Mailing List Server
Using The Bat! as a Mailing List Server by Leif Gregory

What is a mailing list?

There are basically two types of mailing lists. The first is a distribution type, and the second is a discussion type. The distribution type is basically a list where you are providing information in one direction. Typical lists of this type are announcements, newsletters and well, SPAM. These lists are very simple to set up, as about the only thing you have to do is to create an address group with all of the recipients in it. A discussion list is quite a bit more complex to set up. Basically, people send posts (e-mail) to a single e-mail address. From there the post is processed and then sent to everyone in an address book group. The complexity lies in setting up the Reply To:, From:, POP3 accounts etc.

General setup for discussion mailing lists

The easiest way to run a list is to have a separate POP3 account, and as a major plus a forwarding e-mail address (This is a really nice option to have. If you have a forwarding address set up, the e-mail address that subscribers will Un/Subscribe and send posts to will never change. So if you change POP3 servers or give the list over to someone else because you've decided you don't want to run it anymore, you will not impact your subscribers.) To find one of these types of services, just type either "free +email" or "free +POP3" in your favorite search engine. You can set up a discussion list using your existing (main) POP3 account, but it takes quite a bit more work, which I will not cover in this how-to. It will however, generally follow the same guidelines as a stand alone POP3, but your filtering will be a little more complex.

I am going to define some variables so that the below how-to will be much clearer. Please substitute your actual information for that which I have provided.

IDL - The name of our list. It stands for Internet Discussion List

ldgregory@biogate.com - The list moderator's address (Your normal e-mail address)

list@idl.net - The e-mail address that subscribers send their posts and Un/Subscribe requests to.

www.idl.com - The IDL Web site.

IDL <list> - The address book group for normal IDL discussion list subscribers.

IDL Digest <list> - The address book group for digest version IDL list members.

Procedure for setting up the list using a separate POP3 account

First download from http://www.ritlabs.com/the_bat/idl.zip the IDL mailing list account that I have created. You will be "importing" this to The Bat! Imported is in quotes, because there is no actual provision under The Bat! to import an account. I'll explain how to get this account installed into The Bat! in just a minute. I have done about 90% of the work for you, all you have to do is replace the "IDL" information to suit your discussion list, which we will go through step by step.

How to "import" the IDL account into The Bat!

1. Go to where IDL.ZIP was saved when you downloaded it.

2. Double click the IDL.ZIP file.

3. Click the "Extract" button.

4. In the dialog box that comes up do these two things: The "Extract To" field should be the directory that your accounts are stored in under The Bat! In my case it is: C:\Program Files\The Bat!\MAIL. The second thing is to check the "Use Folder Names" checkbox if it isn't already checked.

5. If The Bat! isn't already running, start it.

6. Click "Account", select "New".

7. In the "Account Name" field, enter "IDL".

8. Click the "Next" button.

9. Put your name in the "Your Full Name" field.

10. In the "E-mail Address" field put the forwarding e-mail address you set up for your list. If you didn't set up a forwarding e-mail address (You really should use one of these), then put the POP3 e-mail address that you will be using for the list.

11. The "Organization" field can be left blank or put in the name of your discussion list.

12. Click the "Next" button.

13. In the "SMTP Server" field, put whatever SMTP server you will be using. I have mine set up for my regular ISP SMTP server address.

14. In the "POP3 server" field, put the same address as you used in step 10.

15. Click the "Next" button.

16. In the "Username" and "Password" fields, put whatever your username/login is for the POP3 account you are using in step 14.

17. The two checkboxes are up to you, but I have both unchecked. For the normal operation of the discussion list, you don't need to keep copies of messages on the server.

18. Click the "Next" button.

19. Check the "Do you want to check the account settings now" radio button and click the "Finish" button.

Ok, now that you have "imported" the IDL account, we need to finish setting it up for your discussion list.

How to set up the account for your discussion list.

1. Under the "General" sheet, verify that all the information is correct.

2. Under the "Transport" sheet, verify that all the information is correct.

3. For the first few weeks of your list's "life", you should check the "Deferred" option in the "Delivery" options on the "Transport" sheet. The reason for this, is that you want to make sure that everything is correct in the outgoing messages to be sent to your subscribers before they get sent.

4. Under the "Mail Management" sheet, you shouldn't have to change anything.

5. Under the "Options" sheet, set whatever options you prefer to use. You may want to leave the "Empty trash folder on exit" unchecked for the first few weeks of list "life" also. Sometimes you make a mistake in mail handling, and may accidentally delete a message.

6. Under the "Files and Directories" sheet, you may have to modify the "Home Directory" depending on whether you specified a different "Extract To" path in step 4 of the "How to "import" the IDL account into The Bat!".

7. Click the "+" in front of the "Templates" sheet.

8. Select "New Message". We are now going to set this template up. Hopefully you have given some thought as to what you would like your messages to look like when you post to your own discussion list. The merit to having the below boilerplate:

--

***************************************************

Report problems to: <mailto:ldgregory@biogate.com>

Check the IDL FAQ: <http://www.idl.com/FAQ>

To unsubscribe, click here:

<mailto:list@idl.net?subject=Unsubscribe_IDL>

***************************************************

Is that your subscribers will be reminded each time you post a message to your own discussion list of how to report problems, unsubscribe, and where your discussion list web site or FAQ is. You can make this contain as much or as little information as you want, but I would suggest keeping it short.

Take very careful notice of the two dashes right above the boilerplate. Please note that it is '-- ' (dash dash space). The trailing space is extremely important. What this is for, is that TB cuts off any text following the '-- ' when you reply to a message. How this works in your favor is like this.

You send a message to the list, at the bottom of this message is your boilerplate. Now if you don't have the '-- ', then when someone replies to your message, the boilerplate is quoted. This basically helps you to keep the posts looking nice and clean.

This next block is your macros. Let me show them to you and then I'll explain what they are doing.

%TO="IDL Members <list@idl.net>"

%BCC="IDL <list>"

%RETURNPATH=""

%RETURNPATH="ldgregory@biogate.com"

The Bat! requires that you have a valid e-mail address in the TO field. Putting the discussion lists e-mail address in here serves two purposes. The first is that it looks better than putting in your e-mail address. The second and most important, is that when the message is sent, you will receive it again.

This sounds stupid, but it is necessary if you wish to verify that your message went out without actually subscribing yourself to your own list, and it allows you to keep the message in its final form just like all the other posts that come from your subscribers. This is useful if you want to create a digest version (which I'll get to later in this article), or if you want to place a searchable message archive on a Web site.

The BCC field must contain your address book group that has all of your subscribers in it.. This is very important. If you put the address book group with all of your subscribers in the TO field, then everyone who is subscribed to your discussion list will see everyone else's e-mail address who is also subscribed to the discussion list. This is considered very bad netiquette.

The RETURNPATH is very important in that it provides an e-mail address for bounced messages to come back to instead of your subscribers. Trust me, you have to have it in there, I learned the hard way with my list. Why are there two of them? Well, there's an undocumented feature in The Bat! that allows you to run a macro with a NULL input. What this does is to clear the field so that the second occurrence of the macro can fill it without worrying about what was stored in it previously. This will become much more easily understood when we get to the filtering section (filter four).

10. Select the "Reply" template. Again, you'll want include the boilerplate to remind the subscribers when you reply to a subscribers post. Here are the macros:

%TO""

%TO="%OFROMNAME <list@idl.net>"

%BCC="IDL <list>"

%RETURNPATH=""

%RETURNPATH="ldgregory@biogate.com"

Here's where the NULL value macro becomes a little easier to understand. Let's say "Billy Bob" <bbob@somewhere.com> sends a post. If I want to reply to his message before it gets sent to the list, and send my reply to the list, then I need to change his TO info so that it matches with what we are going to do in the filtering section to all of the messages posted. Namely change the TO, and REPLY-TO information. Again, just hang on a little while and I'll explain this fully in the filters section.

11. This pretty much concludes the account setup. You shouldn't have to use the forward template, and you can put whatever cookies in the cookies template that you want to use.

12. One last thing about the account settings. There are five folders (other than the default ones) included the IDL account. Here's what they are for.

***** Note: If you don't see the below folders, select the IDL account, then hold down the <Ctrl+Alt+Shift+L> keys simultaneously. This will force TB to search for any missing folders in that account.

SPAM - This is the folder I move SPAM to. I'm pretty aggressive in tracking down spammers. If you are interested, I wrote an article for my weekly e-zine entitled "To Catch A Spammer".

Moderated - I've already explained this one, but it is where the messages in their final form (as they were distributed to your subscribers) will reside after the "Move moderated incoming messages" filter processes it.

Failures - This folder will be used to catch bounce messages. Believe me, you will get them. Remember the RETURN-PATH macro? This is what its main purpose is for. Please ensure that the e-mail address you use in RETURN-PATH is different than the one your subscribers use to post and Un/Subscribe to. This will keep the bounce messages from possibly being missed by the filters in your IDL account and getting sent out to your subscribers.

IDL Subscribers - This is the folder that I move the Subscribe requests to, once I have verified that they have been added to the address book. This provides three functions. One is that at a glance, I can tell how many people are subscribed to the discussion list. Two, I have a record of subscribes. This way if someone later on says that I am spamming them, I can prove that they (or at least someone pretending to be them) did indeed subscribe, and three, if someone did not use the correct string to subscribe i.e. they sent a message with the words "Subscribe IDL " in the body of the message as opposed to the subject, you can just copy their e-mail address to the clipboard, right click on the "IDL Subscribers" folder, select "Create a new message" which will create a new message with the "Subscription receipt" in it. All you have to do is paste the subscribers e-mail address into the TO field and send it.

*** NOTE: I have used text files for inclusion into the templates for both "IDL Subscribes" (both filter and folder), and "IDL Unsubscribes" (both filter and folder) that contain the actual text or the Un/Subscribe. This way, if you make changes, you can do it in one place and it updates both the filter and folder versions. If you specified a different "Extract To" path in step 4 of the "How to "import" the IDL account into The Bat!", then you will need to change the directory path in all the templates (both folder and filter) for IDL Un/Subscribes.

IDL Unsubscribers - Serves the same function as the "IDL Subscribers", but is for unsubscribers. If a subscriber messes up the unsubscription process i.e. puts the words "Unsubscribe IDL" in the body as opposed to the subject, then you can cut and paste their address into the "Create a new message" option when you right click the "Unsubscribe IDL" folder.

The Filtering Sub-system

This is the area that will make or break your mailing list. You will need at least four of the five filters that I will be explaining for the basic operation.

1. While the IDL account is highlighted, click "Account" and select "Sorting office/filters"

2. Click the "+" in front of "Incoming messages"

Filter One - Housekeeping

This filter is a housekeeping filter. Because we are changing the TO header in the "Post" filter (See filter four) to "<list@idl.net>" this message is going to come back to you through the normal post e-mail address. You've already processed this message, so you don't want to send it back out to the subscribers again. This is one other reason we are using the RETURN-PATH macro. It is our filter string, whose job it is to move already processed (sent to the list subscribers) messages to the "Moderated" folder (which by the way is where you should make your replies to messages that subscribers have posted.) If you specified a different "Extract To" path in step 4 of the "How to "import" the IDL account into The Bat!", then you will need to change the directory path in this filter to reflect the actual location of the "Moderated" folder.

What we are actually doing with this filter is searching the kludges for the string [RETURN-PATH: ldgregory@biogate.com]. This is something we have modified in filter four to solve two problems: The first is bounce messages get sent to the designated address, and two we can use it as our search string, because it will only appear in messages we have already processed.

Of course you could just send these messages to the trashcan, but if you are going to participate in your own discussion list, it is easier to reply to this message than cutting and pasting all their info during the first time it comes through. Also, if you decide later on to build a searchable message-base on a Web site, you will have the message in its final, post filter-processed form.

Filter Two - Subscribes

The Second filter is the subscription filter. You need to determine what keywords you want to use for your filter string. The easiest, and most logical keywords would be something like "Subscribe" and "IDL". Because not all e-mail clients support the "%20" symbol when resolving a mailto type URL, and also because some do not support actual space characters, I like to use the underscore character between the keywords i.e. "Subscribe_IDL". This is a good way to ensure that whatever e-mail client your subscribers may be using, your URL will work. The added benefit of using the underscore character is that it is almost totally invisible in a URL, because they are almost always underlined. An example of this URL that you would put on a Web pages or in the sig portion of your e-mail messages would look something like this:

To subscribe to the IDL mailing list, click here:

<mailto:list@idl.com?subject=Subscribe_IDL>

If you click on this link, The Bat! will create a new message with the subject line filled in with "Subscribe_IDL", now all the prospective subscriber has to do it click send.

After you have highlighted the filter named "Susbcribe_IDL" do this:

1. Change the filter name in the "Name" field to whatever you wish to call it.

2. Change the filter string in the field "Strings" to whatever you will use as your subscribe filter string.

3. Click the "Alternatives" tab.

What we are going to do here is to try and idiot proof your list a little. Believe me, no matter how hard you try, you will always have people trying to subscribe/unsubscribe from your list using everything but the correct keywords.

The alternatives tab is for "ORing" your filter strings. For more information on this, check the TB help file under "Mail Filtering (Sorting Office)" "Signal Strings".

On this sheet, you will want to change all the different variations of the subscribe signal string to match your list needs.

4.Click the "Actions" tab.

5. Check the "Send Auto-Reply" checkbox.

6. Click the "Template" button.

Here's where you will tell the new subscriber about the list, what to expect, what e-mail address to use to post messages, some rules (concerning flaming, beating a dead horse etc), where to report problems etc. Take some time to think out what you want to put in here. You can use or modify the sample template to fit your needs.

If you read the entire sample, you would have noticed at the bottom there was a macro. It was like this:

%SUBJECT="IDL Discussion List Subscription Receipt."

Because this is a new message created by the filter, you should specify a subject to be placed in the SUBJECT field. The TO field will have whatever e-mail address is specified in the subscribers REPLY-TO information. Here's something important to remember, this message will contain in the FROM and REPLY-TO fields whatever information you have specified in the account that calls this filter (In this case it's the IDL account settings). This is why you should set up a separate account in The Bat! when running a discussion list. You can specify that your FROM information say something like "IDL Discussion List Moderator <list@idl.net>" and your REPLY-TO info "Leif Gregory <list@idl.net>"

7. Also on the "Actions" sheet, you'll see that I have checked the "Add the sender's address to the address book" option. This option allows new subscribers to be automatically added to your address book group for the list. Make sure you change the name of the address book group listed to the one you are using for the list.

***** Note: If you check under the unsubscribe filter (filter three), you'll notice that the option to automatically remove an unsubscriber's address is not enabled. Unfortunately, TB does not currently check to see if the address really exists in the group before deleting it. What this means is if someone tries to unsubscribe from your list, but tries to do it under the wrong e-mail address, then TB will happily comply, but in reality does nothing other than to send them the unsubscription receipt saying they were successfully unsubscribe. Of course this person will probably send you some nasty e-mail when they continue receiving posts to the list. For now, it is better to do it manually.

The way it is set up now, the unsubscribe receipt will still be automatically generated, but you can intervene before it is sent out if the address proved to be incorrect when you manually try to delete them from the address book group.

Filter Three - Unsubscribes

The third filter is your unsubscribe filter. Eventually, someone will want to unsubscribe, so set up this filter similar to the subscribe filter. Of course, you will want to make changes so that it reflects an unsubscribe command. I've included a sample template for you to modify or use as your see fit.

Filter Four - Posts

The fourth filter is the subscriber post filter. This is the real meat of your filtering system, because it allows subscribers to post messages to the rest of the subscribers. This filter will be set up similar to the Un/Subscribe filters, with the following differences:

Under the "Rule" tab, your first filter string should be: [list@idl.net], select the "Recipient" location, and presence is "Yes". This is a SPAM measure. Most times when you receive SPAM, the recipient list has been suppressed, meaning your e-mail address is not displayed along with all the other unlucky recipients of the SPAM. So by specifying "list@idl.net" you will be eliminating a huge majority of SPAM from making it to your subscribers.

The second filter string should be: [Subscribe_IDL], select the "Subject" location, and presence is "No". This will ensure that Subscribe requests don't get sent to the rest of your subscribers.

The third filter string should be: [Unsubscribe_IDL], select the "Subject" location, and presence is "No". This will ensure that unsubscribe requests also don't get sent.

Under the "Actions" tab scroll down till you see "Create a message for", put your name and e-mail address here like this: "Leif Gregory"<list@idl.net> Now click the template button. Here is what the stuff in the template means:

The %TEXT is going to cut and paste the posters text into this message. You don't want to use the %QUOTE macro, because that's not what you want.

The three blank macros "TO, REPLYTO, and FROM" are an undocumented feature in The Bat! What happens when you don't specify any text between the quotes is that it blanks out the field (A NULL value.) Remember when you put your name and e-mail address in the field under the action "Create a message for"? Well, if you don't blank out this field, that info will appear here in addition to the info placed there by the second occurrence of "TO" in the above macro. This is a bad thing. The REPLYTO and FROM fields will contain the information you specified in the IDL account settings, so we want to blank these out.

Ok, now on to the second occurrences of TO, REPLYTO and FROM. When a subscriber posts a message, and the other subscribers receive it, you want the TO, FROM and REPLYTO information to reflect the person who posted the message. i.e. say Billy Bob <bbob@user.com> posts a message to the list. When a subscriber receives the message, you want the TO field to say "IDL Discussion List <list@idl.net>" (unless they were replying to someone's message, then you would want it to have the repliees address here.), you want the REPLYTO field to say "Billy Bob <list@idl.net>" (This is extremely important! The REPLYTO header is the address that is used when someone replies to a message. We want the replies to come back to the list, so that they will get sent to all the other subscribers too. If the replyer wants to send a private message to only Billy Bob, then they should cut and paste the address in the FROM field), which brings up what you want displayed in the FROM field. You want it to say "Billy Bob <bbob@user.com>" (You want the subscribers real e-mail address here.) With that out of the way, let's dissect the macros.

%TO="%OTONAME <list@idl.net>" Remember when I said that you wanted the TO field to display "IDL Discussion List" unless the post is a reply? Here's what happens in this macro. %OTONAME takes all the text except the actual e-mail address i.e. "IDL Discussion List", or in the case of a reply "Billy Bob" and puts it into the TO field. We are then specifying that the e-mail address be <list@idl.net>. So the new TO address will be "IDL Discussion List <list@idl.net>" or in the case of a reply "Billy Bob <list@idl.net>" .

%ReplyTo=%OFROMNAME <list@idl.net> When a subscriber replies to a message, this is the actual e-mail address it will use. We are taking the original posters name and changing the e-mail address so that the reply gets sent to the list instead of the original poster personally.

%From="%OFROMNAME <%OFROMADDR>" Here we are using all of the original posters real information. Their real name and real e-mail address.

%BCC="IDL <list>" This is your address book group entry. Of course we do not want to show everyone on the list who else is also subscribed to the list, so we put it in the Blind Carbon Copy (BCC) field. This also help to prevent spamming of your subscribers.

Filter Five - Move sent messages to trash

This is the filter can do without if you don't want it. However, I would highly recommend it, otherwise the sent posts will accumulate in your "sent" mail folder, and you would have to move them to the trash manually.

Setting up the digest version

Right now, this is one area when The Bat! is kind of weak. I have asked RIT Labs to try and work on this area just a little more. I would have included this section in the filters section, but I didn't feel that it has the proper capability to really be used as a digest generator. There is an option on the "Actions" tab for "Export message to file". The problem is that you can either include all of the kludges (really messy looking), or none of the kludges (difficult to reply to people or to see who wrote the message and it's subject.) I asked RIT Labs if they could allow you to select which kludges to include in the exported message. I think that these kludges are necessary (DATE, FROM, REPLYTO, TO and SUBJECT,). If you wish to experiment around with the digest generator anyway, do this:

In the IDL filters, click the "+" in front of "Incoming messages".

Select "Move moderated incoming messages".

Select the "Actions" tab.

Scroll down till you see "Export message to file".

Put a checkmark in the box.

Click the "Browse" button to the right of the pathname field.

I have already selected the "TBDigest.TXT" file. I'd suggest keeping a copy of all the digests you create for future use (on a web site etc).

If you specified a different "Extract To" path in step 4 of the 'How to "import" the IDL account into The Bat!', then you will need to change the directory path to reflect your directories.

Put a checkmark in the "Append to existing file" radio button.

Exit out of the filters dialog window.

To send a digest to someone (You'll have to do this manually, as there is no way currently to define to TB when to send these digests out.) right click on the "Digest" folder, select "Create a new message". You should be able to just click send from here.

Remember to empty out the "TBDigest.TXT" after sending it, because then you'll just append more messages to the end.

Also remember to set up an address book group called "IDL Digest" (Or change it to whatever.)

Closing remarks and how to contact the author

Ok, we're done. You have all of the stuff necessary to start your own discussion list. If you have any additional questions or find any faults in this how-to, please e-mail me at:

"Leif Gregory <ldgregory@pcwize.com>"

I will be glad to answer any questions you may have.

Troubleshooting

No matter how hard you try, there is always something that didn't get covered. Here are the answers to some common problems people using this how-to have come up against.

The RETURN-PATH doesn't seem to be working / posts that have already been processed and sent out to the list are being treated like new posts when they come back through the system.

Most likely the SMTP or POP server you are using is removing the RETURN-PATH statement from the header. Some are set up this way, and you might be able to get the administrator of that server to change that. If not, then you will most likely have to find a different SMTP or POP server.

To determine which is actually the culprit, create a new message from the IDL list, remove the addresses from the TO and BCC fields (you might have to enable the viewing of these fields first by clicking "View" in the message editor window and putting a check mark next to them.) Once you have cleared out these addresses, put my address <ldgregory@pcwize.com> in the TO field and send it to me. Of course, please type something in telling me why you are sending the message to me. I'll check the headers, and if it is missing, then the culprit is your SMTP server. I will then send you a reply that has a RETURN-PATH statement in it as well, you check the headers to see if it is there. If not, then your POP server is deleting them as well.

I've got a problem with a person who used to be subscribed, but I unsubscribed them because they either didn't follow the list rules or were causing problems. Even though they are unsubscribed, they can still post to the list.

Unfortunately, there is no way to have TB check to see if a post is coming from a person in the subscriber address book group. The only thing I can tell you is to put a filter in the incoming filter section to move their messages to the trash. Make sure you put that filter at the top of the list using the "move up" button. TB checks messages against filters in the order they are listed. Therefore, if you don't put it above at least filter four, then their messages will still get processed

Copyright © 1998-2001 Leif Gregory. All rights reserved.


Dealing with UCE (spam)

The easiest way to get rid of Unsolicited Commercial Email (UCE or spam) is by first excluding all mail that is legitimately for you and then simply considering the rest spam. With this method you hardly ever get legitimate mail ending up in the spam folder or spam ending up in the inbox.

Order is important since TB processes filters from the top down.

First create filters for all your regular legitimate mail.

Then create a filter to place all other messages addressed to you in the inbox or some other created 'sundry' folder.

Then create the spam filter, which is the last filter in the list. Set it up to place the rest of messages that do not satisfy any of the other previous filter rules in a spam folder.

Typically this will be "Any message"

Of course, <empty> means leaving the string blank rather than typing in the word <empty>.

This setup helps you to keep your inbox clean. Very few spammers address messages directly to you and that's one reason why this method works so well. If the message is not from x, y, z, etc or it's not addressed directly to me, then it MUST be spam.

You also add some general spam filters for spam messages addressed to you based on subject content and you can even make them into Selective Download filters so that you won't have to download any such messages to get rid of them.


Folder Maintenance Centre

The Folder Maintenance Centre is invoked by the Folder|Maintenance... menu command of the main window. It allows the user to perform essential housekeeping routines on all or a selected set of folders at once. Here is what you can do:

Integrity Checking

Whenever you suspect that something may be wrong with your folders (especially after having a system crash), you can use this option to make sure that everything is right. This routine performs exhaustive checking of folders' integrity and repairs any damaged folders it finds. Damaged parts are saved into the folder's home directory with a .BIN extension. Those files may contain parts of damaged messages, so you can view them with any binary file viewer (you can find plenty of them by searching the Internet, even the standard Notepad can be used) and save any relevant information you can find.

Removing Duplicates

You may receive duplicate messages from time to time - this depends on many factors, usually down to glitches on a mail server, when the server tries to resend the same messages several times and fails to get confirmation that the message was indeed received. The Bat! allows you to remove those messages so they won't clog your folders. Duplicates are detected by the following combination of message attributes: Message ID, Sender and date of creation.

Purging Old/Excess Messages

You can set message quantity and age limits in the folder properties dialog box, but the messages won't go away automatically unless you've set a folder up to be purged on exit. This option performs a purge of old and excess messages manually. The purge routine may be used to automatically archive old messages in a special folder - if you adjust the Deletion settings of the folder and choose the appropriate deletion method for the Purge operation.

Compressing Folders

This operation has nothing to do with data compression - it is a database compression which is a completely different thing. When you delete a message from a folder, the message still exists in the folder's message base file, i.e. it does not get physically removed, it is just marked as deleted and, depending on your settings, is copied to the Trash folder. This is done for speed and safety purposes. You can use the Folder|Browse Deleted Messages menu command to view deleted messages and resurrect any you deleted by mistake (instead of digging around the Trash folder and moving the message back).

Folder compression actually means that the messages marked as deleted are physically removed from the message base and the folder message base file and index are rebuilt as if those removed messages had never existed. This operation requires a lot of disk work when folders are relatively large, which is why it is not a good idea to use it too often on folders that you rarely delete messages from, especially large ones. However, high-traffic folders, like the Inbox, should be compressed on regular basis to maintain performance - should a folder containing a large number of messages marked as deleted, operations will become significantly slower in that folder.


Backing up your data

To back up your The Bat! data, use the Tools|Backup  menu command of the main window.

The Bat! backup tool helps you to save your data into one archive file. Depending on your needs, you can just save selected address books, accounts and global settings.

You can also choose the "Create Incremental Backup" option in order to create small archives based on the previous archives. Please note that the different file name should be used for new incremental backup archive, The Bat! cannot save data into the same archive for safety reasons.

We recommend that you backup your data on a regular basis, especially when your business depends on e-mail . It's just like a car seat belt - it may not be pleasant to routinely wear it, but it may well save your life one day...

N.B. When backing up from The Bat! to move information into SecureBat! you must use the "Store external attachments in message bodies" option to successfully transfer attachments between the systems.


Restoring data

To restore your data saved using The Bat! Backup tool, simply use the Tools|Restore... menu command.

You may choose to restore several archives at once (e.g: if you have performed incremental backups or backed up several accounts separately) and choose the specific data you wish to restore.


Synchronising between two installations
Mail Synchronisation

Mail synchronisation is one way of keeping two separate copies of The Bat! up to date with each other and is part of The Bat!'s Maintenance Centre. Synchronisation is performed in the following three stages.

1). Creation of data file

This step creates a "map" file that describes the current settings and contents of the selected components (Account data, folders, address book, etc.). Let's call the system performing step 1 'A' and the system that will provide the extra data to it 'B'. When The Bat! maintenance centre on system 'B' reads this file, it can determine which settings and contents it needs to export to give system 'A' the correct data required to synchronise it. When you select this option you will be prompted to name a file in which to store the synchronisation data.

N.B. When synchronising between The Bat! and SecureBat! you must use the "Store external attachments in message bodies" option to successfully transfer attachments between the systems.

2). Storing synchronisation data for system 'A'

This step creates a "differences" file that system 'A' can import to become fully synchronised with system 'B'. When you begin this step on system 'B' you will be prompted to first select the Step 1 synchronisation data file created on system 'A'. You will then be prompted to select or name a file in which the backup data will be stored for submission back to system 'A'.

3). Import of synchronisation data from system 'B'.

This step should be performed on system 'A' and reads a file created by the system 'B' installation of The Bat! in step 2, importing the contents to syetem 'A'. You will be prompted to select the synchronisation backup file (level 2) to use for this operation.


Saving data between system installations

From time to time, people need to reinstall their operating system. This usually leads to reinstalling all software they use, The Bat! is not an exception. The biggest problem system reinstallation creates is keeping data your software uses intact. Here are the ways to overcome this problem when it comes to The Bat! data:

Method No. 1. The simplest way

The simplest and the most universal way to reinstall The Bat! is to save your data using the Backup tool, reinstall the system, install The Bat! and choose to restore from a backup archive when you are prompted to create an account. The drawback of this method is that a potentialy large data volume may be processed when unnecessarily, therefore here is

Method No. 2. A slightly more complicated but faster way

If you are not going to change the location of your mail directory or reformat your hard drive, simply export the Registry key HKEY_CURRENT_USER\Software\RIT\The Bat! to a file using the RegEdit (just start it by using the Start|Run Windows menu command, type "REGEDIT" and press Enter), reinstall your system and  import the .REG file back to the Registry. Then, install The Bat! and enjoy yourself.


Transferring data to another system

Whenever you want to transfer your The Bat! data to another system (for instance, when you buy a new PC), just backup your data using the Tools|Backup... menu command of the main window, select the data you wish to transfer (accounts, folders, address books, settings). Then, transfer The Bat! to the other system, install The Bat!  and choose the option to restore data from a backup archive when you are promted to create a new account.

N.B. Before you install The Bat! on another system, make sure there is sufficient free disk space on its drive - the minimum amount of free space should be at least four times larger than the size of the backup archive.


About SmartBat

SmartBat is a small notepad editor providing a convenient way to create and manage personal notes. To open it, use the Tools|SmartBat menu command or just use the Alt+F11 key combination. You can also reach it from the Scheduler because they are located in the same window on different tabs.

SmartBat can maintain multiple pads - a SmartBat's Pad is a simple text file. To create/open a new Pad, just press Ctrl+N and choose the name of the file (if the file does not exist, it will be automatically created). The <MAIN> Pad of the SmartBat is kept in the SMARTBAT.TXT file.

Here are some ideas of how you can use the SmartBat:

•	Thought keeper: just fire up SmartBat and type a valuable idea that came to you while you were reading your mail

•	Clipboard extender: to keep clips of text so you can quickly access them from anywhere on your system by setting a System Hot Key for SmartBat (you can even use the system-wide hot key inside The Bat! for coping/pasting data while a modal dialogue is active)

•	Cookie/Template manager: to maintain your Cookie files and external templates (those included by the %INCLUDE="filepath" macro)

•	Digest reader/Text file monitor: for quick access to digests created with filters that export messages into files

With the calendar, you can easily find tagged records with dates close to a given date.

Quick search helps you to quickly search for specific words. Just enter the word you want to find and press <Enter>


Using menu commands

If you click the right mouse button while using SmartBat, a pop-up menu with a list of commands is shown. The first commands are available in every text editor, they are: Undo <Ctrl+Z>, Copy <Ctrl+C>, Cut <Ctrl+X>, Paste <Ctrl+V>, Delete , Select All

New Pad... Use this to open a new Pad. The shortcut is <Ctrl+N>

Next Pad If you have several Pads open and want to switch to the next one you can use this command or the shortcut <Ctrl+Tab>

Previous Pad If you have several Pads open and want to switch to the previous one you can use this command or the shortcut <Shift+Ctrl+Tab>

Close Pad Use this command to close the current pad or the shortcut <Ctrl+F4>

Save as... Save your notes to disk as a text file. The Shortcut is <Shift+Ctrl+S>

Utilities is a submenu with more advanced commands, it is described in the Utilities sub-menu commands topic.

Exit Use this to exit the SmartBat window or press either <Esc> or <F6>


Utilities sub-menu commands

The Utilities menu commands are available in the Utilities sub-menu of the SmartBat.

Insert Time Tag Line inserts a line with following format:

>======< 8/30/2003 1:49:55 AM >====================(20030830)========

It contains the current date and time and its purpose is mainly to separate notes. The shortcut for the command is <Shift+Ctrl+T>

Insert current date insert today's date at the position of the cursor

Insert current time insert current time at the position of the cursor

Evaluate command evaluates an arithmetic expression, for example:

(45-32)*678.08\

When executing the evaluate command, the cursor should be positioned in the line containing the first number/symbol of the expression. There must not be any spaces between signs and numbers. You can use brackets to separate some operations. After calculation, the entire expression is replaced with the result. For quick access use the shortcut <Shift+Ctrl+=>

Format block contains Left <Alt+L>, Right <Alt+R>, Justify <Alt+J>, Centre <Alt+C> commands that can be applied to the current line.

Auto format is a convenient utility that allows the automatic formatting of text such as links, e-mail addresses, etc. The shortcut is <Shift+Ctrl+F>

Auto wrap automatically wraps lines. This is a good way to write well-formatted text without having to break lines manually. The shortcut is <Shift+Ctrl+W>

Justify on autowrap automatically justifies the text when carrying a word over to the next line with the auto wrap option on. The shortcut is <Shift+Ctrl+W>

Copy to... if you select some text and choose the Copy to command, the Write block to file dialog window will appear where you can select a text file or create a new one to write the selected text into.

Paste from... displays a Read file as block dialog window where you can choose a file you want to paste into the Pad as text.

Paste formatted paste the text from the system clipboard in the same format as it was copied. The difference between this and the Paste command can be seen when copying text from (for example) a RTF editor. Using Paste formatted allows you to copy a part of a doc file with the same wrap formatting. The shortcut is <Shift+Ctrl+Ins>


Using the scheduler

The Scheduler is a new feature, introduced in version 2. Use it to arrange appointments and to automatically execute actions such as running programs, creating/sending mails and opening different types of documents.

You can start it from the Tools | Scheduler sub-menu or just press <Alt+F6> You can also start the SmartBat utility and click on the lower tab – both tools are integrated into the same window.

The Scheduled Tasks list is in the top left corner, a tree designed for quick access to today's, tomorrow's and a whole week's tasks with sub-levels containing all tasks for the same day marked as important. (Note: important tasks are included in both levels). There is also quick access to Repeated Tasks and Current tasks.

In the bottom left corner there is a calendar to make it easy to browse dates and on the right side there is a table with tasks selected from the Scheduled Tasks or the calendar. The columns shown are:

1.	Description a short description of the task

2.	Importance the priority of the task

3.	Next the time the task will be executed again

4.	Stops the time the task will be stoped

5.	Recurrence shows if the task is recurrent

6.	Starts the time the task will start

7.	Ends the time the task will stop

To add a new task click the right mouse button and choose new from the popup menu, or just press <Ins>

The create and edit task commands both bring up the "Edit Event" dialog window where you can edit the task settings. There are General, Action, Recurrence, Advanced, Links and Categories tabs available

Useful tip

You can quickly create a reminder about from messages. Just select a message in the preview pane, go to Specials | Remind later and choose when you want to be reminded: Tomorrow, Next Week, Next Month, Every day next week, Next month every week. Under advanced you can set up advanced options for the linked message.


General

The general tab contains the Description area where you can give a short description of the task, Start and duration of the task, priority (lowest, low, normal, high and highest values are available. Note: if you set the task priority to high or highest it will show up under the Important sub-leaf of today, tomorrow and this week leaves). If you want to be notified about the task in advance, check the "Notify me about this event" checkbox and set up values for when you want to be notified. Click on the Notification parameters button to bring up a dialog where you can set up the way in which you want to be notified.

In the Notification parameters dialog you can choose any combination of playing a sound, using the system speaker and activating a notification window. Use When notification is not confirmed play sound each checkbox if you want to be prompted by sound when the notification is not confirmed. Also, by checking Set as default you can set the current parameter combination to be used for all tasks. Press OK to get back to Event Edit dialog.

There is Notify about up to checkbox that if checked, will notify you about missed events. You can also check Execute action for missed events if you want a missed task action to be executed at startup anyway.


Actions

In the Actions tab you can set what activity is to be performed when tasks start and end. When you click on the Add button a pop-up menu window is shown. You can either start a program, send/check mail boxes, create/send a message or open linked documents.

Start a program

If you choose start a program, you will see a dialog windows with the following values:

Program: - a program to be executed when the task starts

Command line parameters: - command line parameters for the program.

Application window display mode - you can start a program in Normal, Maximised, Minimised, and Hidden modes.

Run console application as a detached process - this checkbox is for running the console as a separate process from The Bat!.

Check/send mail

If you choose check/send mail a check/send dialog window mail appears. This is where you can set up:

In the Action to perform area you can choose between Check for new mail only, Send Queued message only and Check and Send mail simultaneously.

Use Accounts to choose which mail boxes you want to check/send mails for.

Connect to internet if needed - lets you connect to the internet automatically when you use a dial up connection

Disconnect when all sessions finished - check this if you want to end your dial up access after the program is done with checking/sending mails

Create/Send message

The Create/Send message option brings up the Create/Send message dialog window where you can create a new message and set parameters for sending it.

First you have to choose which account you will use from the Use account list. After that enter the address of the recipient in Create message for area.

You can choose either Linked person/ addresses (defined in the links tabs) or an address from the Address book  by pressing the Browse button.

You can create the body of the message you want to send in the Source section. You can use edit to create a specific template, or select a Quick Template from a list. Check Attach linked documents if you want documents defined in the links tabs to be sent as attachments to the message.

The last step is to select which action is to be performed on the message: send immediately, queue in the outbox, open in the message editor or save as a draft message in the outbox. If you set a list of addresses that the message is to be sent to and you want it to be sent as a separate message to each address, then check the Create a separate message for each address checkbox.

Open linked documents

If you choose Open linked documents the Open Links dialog appears. The following options are inside:

Start this action when notification is confirmed start the action when notification has already occurred and was confirmed by user.

Search a message in other folders in case it is moved By using this option you can make sure that a message will be sent even if it was moved. By clicking on 'Folders' you will bring up a dialog containing the Accounts and folders tree where you can select the folders to be searched.

Open messages only if it complies with following options This option will open a message only if certain conditions apply. You can choose from a list of message flags such as Replied, Not Replied, Flagged, Not Flagged, Forwarded, Not Forwarded, Read, Unread, Belonging to any marked colour groups bellow, Not of any marked colour group bellow.

If you mark any event in the start action list and click Edit it will be opened in a dialog with the settings you previously gave it. If necessary, enter new values and click the Ok button to save them. The Delete button removes the selected action from the list.

Execute this action when event finishes contains the same options as the Execute this action when even starts dialog. This list will be executed following an event.


Recurrence

The Recurrence tab allows you to set up repeating parameters for the task. To set up certain conditions, check the Repeat this event every checkbox and enter appropriate values in the edit box. You have to enter a frequency and choose between seconds, minutes, hours, days, weeks, months and years. By default the event never stops. You can also choose to stop the event after a number of occurrences or at the date when you want the last repeat to occur.

Note: When you check the Repeat this event an addition Advanced tab, where you can set up more precise options for Recurrence.


Advanced

For more precise conditions on occurrence the Advanced tab offers you a rich option set. You can browse in the same way as you use tabs to set what time of a day you want it to start, or select which week days, weeks or months of a year. For the time you can set the time at which it should start, the repeat frequency and the from/to time at which you want it to occur or you can set a time mask in Cron format

Under days you can set it to occur every day, every weekday, weekends only, only chosen days of a week or you can provide a list of month/year/vCalendar/iCalendar days.

Under weeks you can choose either every week, specific weeks every month or to provide a list of weeks of a year in number format separated by commas (for example 1, 24, 37).

Under months you can choose either every month or specific months of a year from a list.


Links

The Links tab contains a list of URLs, files and personal contacts from the Address Book. This list is used when you create a message associated with an event, so you can attach it to the message or use them as recipients of the message. If you click on the add button, you will see a pop-up menu with following options:

Add a file add a file to the list from the standard file open dialog.

Add an URL opens a dialog window where you can enter an URL for the resource.

Paste an URL pastes an URL into the list from the system clipboard.

Once a list has been generated, you can select one of the items and use the edit button to change the setting. Clicking the delete button after selecting an item will remove it from the list.

In the Persons section you can construct a list with contacts from your Address Book. A click on the Add button will open the Pick e-mail addresses dialog. Once you have already added some contacts, you can select any of them and use the Edit button.

The Edit address entry dialog will appear and you will be able to edit the selected contact. Using the Delete button removes the selected contacts from the list.


Categories

The Categories tab is designed for the future use. You will be able to construct a personalized tree view of the tasks.


Cron format

Cron format is a simple and flexible way to define a time and frequency for various actions. There are classic and extended modes of cron format.

The classic version of cron format consists of five fields separated by white spaces:

<Minute> <Hour> <Day of the Month> <Month of the Year> <Day of the Week>

The extended  version of cron format has an additional (6th) field: <Year>:

<Minute> <Hour> <Day of the Month> <Month of the Year> <Day of the Week> <Year>

The following list shows the range of each field:

Year (range: 1900-3000)

Day of the Week (range: 1-7, 1 represents Monday)

Month of the Year (range: 1-12)

Day of the Month (range: 1-31)

Hour (range: 0-23)

Minute (range: 0-59)

When composing a cron format time any of these 6 fields may be an asterisk (*). This would mean the entire range of possible values, i.e. each minute, each hour, etc. In the first four fields, users can also use the "nonstandard" character ? (question mark).

Any field may contain a list of values separated by commas, (e.g. 1,3,7) or a range of values (two integers separated by a hyphen, e.g. 1-5).

After an asterisk (*) or a range of values, you can use the character / to specify that values are repeated over and over with a specific interval between them. For example, you can use "0-23/2" in the Hour field to specify that an action should be performed every two hours.

In the Month and Day of the Week fields, you can also use the names of months or days of the weeks abbreviated to the first three letters ("Jan,Feb,...,Dec" or "Mon,Tue,...,Sun") instead of their numeric values.

Examples:

25 14 17 8 * *                  Every  year, on August 17th at 14:25

59 23 31 12 5 *               One minute  before the end of year if the last day of the year is Friday

* * * * * *                         Every minute


iCalendar

iCalendar is a common format for openly exchanging calendar and scheduling information over the Internet. You can read more information about it in RFC 2445.

Follow this format to write an iCalendar recurrence string:

"FREQ"=freq *(

                ; either UNTIL or COUNT may appear here,

                ; but UNTIL and COUNT MUST NOT occur in a same string

                ( ";" "UNTIL" "=" enddate ) /

                ( ";" "COUNT" "=" 1*DIGIT ) /

                ; the rest of these keywords are optional,

                ; but MUST NOT occur more than once

                ( ";" "INTERVAL" "=" 1*DIGIT )          /

                ( ";" "BYSECOND" "=" byseclist )        /

                ( ";" "BYMINUTE" "=" byminlist )        /

                ( ";" "BYHOUR" "=" byhrlist )           /

                ( ";" "BYDAY" "=" bywdaylist )          /

                ( ";" "BYMONTHDAY" "=" bymodaylist )    /

                ( ";" "BYYEARDAY" "=" byyrdaylist )     /

                ( ";" "BYWEEKNO" "=" bywknolist )       /

                ( ";" "BYMONTH" "=" bymolist )          /

                ( ";" "BYSETPOS" "=" bysplist )         /

                ( ";" "WKST" "=" weekday )              /

                ( ";" x-name "=" text )

                )

     freq       = "SECONDLY" / "MINUTELY" / "HOURLY" / "DAILY"

                / "WEEKLY" / "MONTHLY" / "YEARLY"

     enddate    = date ; Example: The following represents July 14, 1997:  19970714

     enddate    =/ date-time            ;An UTC value.

         ;Example: The following represents July 14, 1997, at 1:30 PM:  19970714T173000Z

     byseclist  = seconds / ( seconds *("," seconds) )

     seconds    = 1DIGIT / 2DIGIT       ;0 to 59

     byminlist  = minutes / ( minutes *("," minutes) )

     minutes    = 1DIGIT / 2DIGIT       ;0 to 59

     byhrlist   = hour / ( hour *("," hour) )

     hour       = 1DIGIT / 2DIGIT       ;0 to 23

     bywdaylist = weekdaynum / ( weekdaynum *("," weekdaynum) )

     weekdaynum = [([plus] ordwk / minus ordwk)] weekday

     plus       = "+"

     minus      = "-"

     ordwk      = 1DIGIT / 2DIGIT       ;1 to 53

     weekday    = "SU" / "MO" / "TU" / "WE" / "TH" / "FR" / "SA"

     ;Corresponding to SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY,

     ;FRIDAY, SATURDAY and SUNDAY days of the week.

     bymodaylist = monthdaynum / ( monthdaynum *("," monthdaynum) )

     monthdaynum = ([plus] ordmoday) / (minus ordmoday)

     ordmoday   = 1DIGIT / 2DIGIT       ;1 to 31

     byyrdaylist = yeardaynum / ( yeardaynum *("," yeardaynum) )

     yeardaynum = ([plus] ordyrday) / (minus ordyrday)

     ordyrday   = 1DIGIT / 2DIGIT / 3DIGIT      ;1 to 366

     bywknolist = weeknum / ( weeknum *("," weeknum) )

     weeknum    = ([plus] ordwk) / (minus ordwk)

     bymolist   = monthnum / ( monthnum *("," monthnum) )

     monthnum   = 1DIGIT / 2DIGIT       ;1 to 12

     bysplist   = setposday / ( setposday *("," setposday) )

     setposday  = yeardaynum

Here are some examples of iCalendar recurrence:

"The last working day of the month" could be represented as:

FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-1

The following is a rule that specifies 10 meetings that occur every other day:

FREQ=DAILY;COUNT=10;INTERVAL=2


Connection to The Internet

You can choose your preferred method of connecting to the Internet in the "Network and Administration" dialog box using the "Network" tab.

The Bat! supports two ways of connecting to the Internet

Using Local Area Network or manual connection

If this method is chosen, The Bat! uses an existing connection to the internet which has been established either through your LAN or by manually dialling your Internet Service Provider. In other words, The Bat! relies on the connection to the Internet already being established and the program itself does not need to do anything extra. Some non-LAN systems may be configured so that an ISP is dialled automatically whenever an Internet program tries to connect to an Internet server. This can be used with The Bat! However, in some cases The Bat! needs to instate two TCP/IP sessions simultaneously and this could cause problems such as trying to establish two dial-up connections at the same time.

Dial-Up Networking Connection

You need to specify this type of connection if your LAN is not connected to the Internet itself and you are using a Dial-up connection provided by your ISP. Whenever The Bat! needs to open a TCP/IP connection, it checks whether or not a specified 'phone book entry is active (i.e. the established TCP/IP connection, if there is any, has been made using this 'phone book entry). If the entry is active, the TCP/IP sessions start. Otherwise, The Bat! automatically dials the 'phone book entry to establish a TCP/IP connection. In this case, multiple requests such as checking mail for all accounts and combined delivery (which requires two TCP/IP connections to be open at once: one for mail retrieval and another one for sending mail) will be handled correctly.

Auto-disconnect after mail transmission - Use this option if you do not want to remain on-line when The Bat! has finished dealing with mail transmission. This feature is most useful in combination with the periodic mail retrieval (especially when you have to pay for calls to your ISP).

Pause between dialling session - This value determines the shortest interval between two consecutive dial out sessions. Use of this feature is essential in a multi-user environment with a single dial-out machine - it prevents the dial-out machine from dialling the ISP too often. Note that manual requests for mail retrieval by the dial-out machine will initiate dialling even during the pause time

Your machine status

If a machine is not a part of a Local Area Network, or all machines in your network have TCP/IP protocol installed, or you simply do not intend to read your mail from other machine within your LAN, the status of your machine is TCP/IP Workstation.

If a machine is connecting to the Internet by either LAN or Dial-up networking and it is intended to retrieve and send mail for all accounts defined in The Bat!, the status of your machine is TCP/IP or Dial-out Server.

If a machine does not have TCP/IP protocol installed and it is a part of a network with TCP/IP or Dial-out Server, it must have a status of Non-TCP/IP Workstation.

You can configure this setting using the "Change" button in the "This machine is" area of the "Network and Administration -- Network" dialog box.

See also:

Working in Multi-User Environment

The Bat! Networking Course


Connection Centre

The connection centre displays the progress and status of The Bat!'s on-line activities. A pie chart displays the progress of message transfers while the Queue list box displays lines to indicate the queued tasks per account. These tasks can be deleted from the queue or aborted once they have started.

At the bottom of the lower section (and you can use the scroll bar to view this) is a log panel which shows a transcript of recently completed queued tasks.

You also have access to the current phone connection (if you are using dial-up connection from within The Bat!) and can control some elements of it from here.


Working in Multi-User Environment

If you want to share access to Internet mail between several users, you may need to set access rights for particular accounts or account groups.

Users are classified in two categories:

Administrators - these users can see all accounts defined in the running copy of The Bat! and can change all account properties, program preferences and settings.

Ordinary Users - these users cannot see all defined accounts. The properties they may change are determined by the Administrators.

If at least one ordinary user is defined, an initial Log on dialog is invoked at the program's start-up and a user has to enter his/her account name and password (if any) to have access to his/her account. The password for a particular account can be set using the "Account | Set Access Password" command from the main program window.

To allow an ordinary user to have several accounts and to see them simultaneously, the Administrator must define an account group for that user.

Within a network, it is possible to give access to a particular account from a machine connected to the network. All the Administrator needs to do is to set the account's home directory to a directory accessible on the network and to create a copy of the account on the machine from which the account is going to be accessed. Even if machine does not have the TCP/IP protocol installed on it, it is still possible to use The Bat! - just define the machine as a Non-TCP/IP Workstation and the working directory of the copy of The Bat! running on the machine to be the same as that of a machine which is running The Bat! with the status of TCP/IP or Dial-out Server.

See also:

The Bat! Networking Course

NB: These multi-user features are not available for SecureBat! since the security is very much centred around single user with strong privacy and security requirements.


The Bat! Networking Course

Introduction to E-Mail Exchange

See the section on the Internet for a background to the growth of the global phenomenon that is the Internet.

In order to handle E-Mail exchange within either the Internet or a corporate network, each E-mail client should have either a permanent or an on-demand connection with a mail (POP and SMTP) server. A mail server is a computer that processes the distribution and storage of E-Mail messages until they reach their destination address. A generic E-mail client supports at least two of the most commonly used E-mail exchange protocols: POP and SMTP. POP (Post Office Protocol) is used for retrieving mail from a host by a client. Mail message exchange is initiated at the client's request. SMTP (Simple Mail Transfer Protocol) is a simple protocol for mail transmission that is widely used on the Internet. The SMTP server's function is to receive mail from other servers and clients, and to deliver mail to other hosts and, ultimately, to its clients' mailboxes.

Networking Modes of The Bat!

The Bat! can work either as a stand-alone program or as a replacement for a mail (POP/SMTP) server within a local network (e.g. Windows Workgroup, Windows NT Domain or Novell Netware) at the same time as providing the client part. There are three network modes in which The Bat! can function: stand-alone (TCP/IP Workstation), server (TCP/IP or Dial-Out Server )or client (Non-TCP/IP Workstation).

TCP/IP Workstation: the  stand-alone  mode

The Bat! acts as a generic e-mail client in this mode. A generic e-mail client must have a connection to its mail (POP/SMTP) server(s), which can be located either inside in the corporate network or somewhere on the Internet. The Bat! can connect to the Internet in one of two ways:

Local Area Network or manual connection. If this connection method is chosen, The Bat! uses the connection to the Internet already established either via your LAN or by dialling your Internet Service Provider. In other words, The Bat! itself does not need to do something extra to connect to the Internet. Some non-LAN systems may be configured so that the ISP is dialled automatically whenever a program tries to connect to an Internet server and this method can be used with The Bat! However, in some cases (combined delivery or multiple account operations), The Bat! has to establish two or more TCP/IP sessions simultaneously and this may cause problems such as trying to establish two dial-up connections at the same time. We recommend using the second connection method if you have a Dial-up connection to your ISP

Dial-Up Networking Connection. You should specify this type of connection if your LAN is not connected to the Internet itself and you are using a Dial-up connection provided by your ISP. Whenever The Bat! needs to open a TCP/IP connection, it checks whether or not the specified 'phone book entry is active (i.e. the established TCP/IP connection, if there is any, has been made using this 'phone book entry). If the entry is active, the TCP/IP sessions start. Otherwise, The Bat! will automatically dial the 'phone book entry to establish a TCP/IP connection. In this case, multiple requests such as checking mail for all accounts and combined delivery (which requires two TCP/IP connections to be open at once: one for mail retrieval and another one for sending mail) will be handled correctly.

TCP/IP or Dial-out Server: the  server  mode

It is possible that client computers in a local network have no access to the Internet or that there are some restrictions in force that prevent these computers from using mail transfer protocols. In order to provide users of such machines with E-Mail exchange facilities within the Internet and/or the corporate network, there must be a mail (POP/SMTP) server within the workgroup or domain.

The Bat! in server mode can replace a mail server for such a network. This means that it enables you not to need a mail server inside your local network and, moreover, it gives users the possibility of processing E-Mail exchange over the Internet without having their own Internet connection. A computer with The Bat! in server mode is basically the same as in stand-alone mode with the addition of the use of its own Internet connection to provide E-Mail exchange with computers with The Bat! in the client mode over the network and/or the Internet.

Non-TCP/IP Workstation: the  client  mode

The Bat! in client mode uses neither Internet nor local connection to a mail (POP/SMTP) server for E-Mail exchange. It uses The Bat! in the server mode within the network to which it belongs. There is no limit on the number of computers which  can run The Bat! in client mode within a network as long as the server machine is unique for each group of client machines. This latter point also means that it is possible to have several groups of client machines using different servers but those groups cannot intersect.

Setting up The Bat! Networking- The Bat! Networking: How Does This All Work

All account data and message bases that are used by computers in client mode are located on the server computer and the data is accessed using the local network.

When the user of a client machine wants to send a message to an Internet address, it places the message into the Outbox which is physically located on the server machine. It then sends the command that makes the server send the outgoing messages using the server's connection to the Internet.

When a client wishes to check its POP account, it sends the command to the server to check the client's mailbox on the mail server. The server connects to the POP server using its own Internet connection, receives the messages, stores the messages in the client's message base and sends the command to the client to re-read its message base contents. When the client receives this command, it notifies the user that the new mail has arrived. The new message arrival is indicated in the folder tree screen of the client, and on the MailTicker ™, if the MailTicker™ is configured for use.

To turn on the MailTicker™ (there must be some unread messages for the MailTicker™ to scroll), use the "Options | MailTicker™ | Show Always" or "Show Automatically" options of the main window menu.

Setting up a TCP/IP or Dial-out Server (server), Step by Step

1. Within your local network, select a computer, which is connected to the Internet. This computer will be the "TCP/IP or Dial-out Server" (server).

2. Using the "My Computer" desktop icon, choose the local drive or directory in which The Bat! is installed or where you are planning to install The Bat!. This location will be used to store the message bases. Make this path available as a "network share" for the users that are going to run The Bat! in client mode on their computers. If you are already using a network drive, e.g. on a dedicated file server, you may skip this and the next step.

3. Map the shared resource from step 2 to a network drive letter. Other computers that are going to act as clients within your network will use this network drive to exchange information with the server.

4. If you do not have The Bat! installed yet, install it to the mapped network drive in order to allow machines running The Bat! in client mode to access it. Run The Bat! from the newly mapped network drive.

5. Click the "Network & Administration" item of the "Options" menu to make sure that this machine is in "TCP/IP or Dial-Out Server" (server) mode.

6. Create the accounts that will be used by the client machines. Make sure that the home directories of these accounts are located on the network drive so that the client users can access them.

7. Invoke the "Network & Administration" dialog box again and configure the privileges of the accounts you have created.

Setting up a Non-TCP/IP Workstation (client), Step by Step

1. Map the shared resource from the server to the same drive letter as it is mapped to on the server.

2. When installing The Bat! on a client machine, select the program's working directory on the network drive letter that you have just mapped. The working directory must be the same as that on the server.

3. If you have already The Bat! installed on this computer, please perform the following steps, otherwise, if you just have installed The Bat! according to the previous steps, the setup is complete.

These sub-steps describe how to change the machine from stand-alone to client mode without having to reinstall The Bat! If you are not familiar with the use of RegEdit, it would be better for you to uninstall The Bat! and to go to the step entitled "Installing The Bat! on a client computer"

 a) Open the "Network & Administration" dialog box and make sure that this machine is set up as a "Non-TCP/IP Workstation".

 b) Exit The Bat!

 c) Change the mail directory using RegEdit. Open RegEdit and navigate to the HKEY_CURRENT_USER\Software\RIT\The Bat! key, look for the entry called "Working Directory". The value data is the path to the mail directory, which should be changed to match the network drive, and it made the same as that on the server.

Using The Bat! As a Core Element of E-Mail Exchange within a Corporate Network

There may be reasons to have an E-Mail Exchange system for local corporate networks that have neither POP/SMTP servers nor Internet access. In this case, there must be a local message delivery system, i.e. the messages must be routed, delivered and stored locally without using POP/SMTP servers.

Local Delivery Technology is provided by The Bat! when the appropriate option is turned on. To activate it, open the "Network & Administration" dialog box on the server, and tick the "Allow Local Delivery" checkbox. This option allows several machines to work in a local network exchanging messages without using n SMTP/POP server at all. This feature provides a very efficient solution for building corporate mail-exchange networks without using Internet Mail Transfer Protocols. When the "Allow Local Delivery" option is on, outgoing messages addressed to local users are delivered directly into the appropriate message bases instead of having to send them to an SMTP server.

See also:

Working in Multi-User Environment

Account Groups


Account Groups

If a particular user wants to have access to several e-mail accounts, it is possible to define a group of accounts, which are displayed whenever that user logs on to The Bat!

To define an account group, use the "Options | Network and Administration" menu command from the main program window.

To log into The Bat! for access to an account group, just enter the group name and password instead of an account's logon data when prompted in the login screen.

See also:

Working in Multi-User Environment

The Bat! Networking Course


General Preferences

Always show icon in the System Tray – naturally The Bat! icon will be permanently displayed in the System Tray.

Do not display program icon on the Task Bar – The Bat! window will not be seen among the rest of the minimised/open windows on the Task Bar. Note that the next menu will also be checked.

Minimise to the System Tray – this will minimise The Bat! to the System Tray and it will not be seen, however the small icon indication that the programme is running will be invoked automatically.

Icon animation when unread messages are detected – The Bat! starts weaving its wings whenever there are unread mails in any account.

Use external viewer to open attached images – upon clicking on the attached image The Bat! will not open it using the built-in viewer, but the system one, to which a particular extension is assigned.

High colour images (change effective after restart) – if that options is unchecked all the icons in The Bat! interface will look ugly in case the programme is "dressed" into a non-standard skin.

Inform about birthdays using address book data – if there are any entries in your default address book containing birthday data and this option is checked The Bat! will tell you on that day that a particular person is celebrating his/her birthday. It may happen in two ways depending on whether the programme is running or not. If The Bat! is running you will get a notification at midnight of the day on which someone has a birthday. If you open The Bat! on that day then the notification will appear at start-up.

Display MenuNavigator button on the Caption Bar – if you untick that option the "?" button will disappear from the top-right corner of The Bat! window.

Close the separate viewer parent window when replying/forwarding – in The Bat! you can open messages in separate windows and when replying/forwarding a message that window will be closed.

Use X-Mailer header in messages (for administrative purposes) – this option is off by default. If you turn it on then people will see what is the programme that created the e-mail message, i.e. The Bat!. It may be possible that some ISPs with really lazy administrators consider The Bat! to be a spam-ware and thus block all messages that contain The Bat! in the X-Mailer header.

Start program after system halt – if your system freezes and you are forced to restart it using the Reset button then The Bat! will be loaded at windows start-up.

Display Connection Centre – 3 options are available: automatically – the window will appear and disappear automatically, i.e. after sending/receiving messages, always – the window will always stay in the Task Bar, hide – the window will not be seen at all.

Default Virtual Folder name template – you can define the standard template for the names of this type of folders. The only macros available is %NAME which is replaced by the real name of the virtual folder. This may be useful for making visual difference between usual folders and virtual ones. A simple example of such a template is "* %Name *" (quotation marks should be stripped) - using of this template will make all virtual folders listed in the tree with names embraced by asterisk characters.


System preferences

(System page)

Mail Directory – the directory where all the new accounts will be created and where The Bat! stores its data. Can be changed, but be careful when you are doing this!

AutoComplete – when composing a message addresses and subjects can be picked up from previously created messages. If for some reason you do not want the programme to offer it, simply uncheck that option.

When logging events, use system alarm sound for – beside the error message in the log (which you may miss), you will hear the sound attracting your attention.

Extended mouse button functions – to make your experience using The Bat! even more pleasant you can assign the mouse buttons additional functions, that will help speed up the work with the ever-increasing amount of messages. Please do not get surprised when you discover that extended buttons on your mouse do not work as you expect - many mouse drivers do not support the standard specification and simply map the buttons to Alt+Arrow key combinations.

Account tree font – if you want to change the font used in the account and folder tree pane of the main window – it's the best place to do it.

(Applications page)

Associate The Bat! with specific file types/URLs – the listed file extensions will be associated with The Bat! for more convenient work, so whenever you open the file from the Explorer, The Bat! should start and display the file as a message (for .MSG and .EML files), as an address book record (for .VCF files) or start a new message when you click the mailto: link.

Simple MAPI - Simple MAPI is a programme interface used by many applications helping them to communicate with e-mail client in order to create/send/access messages generated by those applications.

Check that The Bat! is the default mail client at startup – if the option is active the programme will check if it set as the default mail client.


Message preferences

Automatically adjust first column width for threaded views – as the message thread is expanded more and more – The Bat! will adjust the first column in width in order to optimize the whole view of the thread, so that it can stay on the screen as much as possible.

The oldest message begins a thread by Subject/From/To – check that option and the messages of a thread will be sorted starting with the oldest one.

When moving to the next/previous unread message across folders – set the programme to behave the way you want it by selecting any of the given options.

Allow search for unread messages across accounts – this will enable searching for unread messages in different accounts when all messages are read in the current account.

Use PC Speaker for beeps – this enables the system speaker to sound instead of your sound card, so you hear the beep even when your external speakers are switched off.

Date/Time display – there are several types of displaying the date available. You can change it according to your personal preferences.

Message Headers

An email has two essential parts: the body (or content) and the headers. The headers are the lines of text at the beginning of an email that document its travel history.

Headers contain a wealth of information about your email. They tell you which machines handled your message, and how long they took to send it to you. They can tell you who sent the message, and who it was destined for. However, headers can be misleading. It is fairly simple to write fake headers, which obscure information about the sender, recipient, and the machines that handled the mail.

Any field starting with an X- is an optional field added by the user, their email client software, filter system, or mailing list manager.

Here, you can edit the list of message header fields that can de displayed at the Header of the message preview pane without opening a message source view or switching display of unparsed headers.


System-Wide Hot-Keys

Certain functions within The Bat can be assigned to Hot-Keys which are available system wide, whether or not The Bat! has the focus. You may assign any valid keyboard and shift key (including <Alt> and <Ctrl>) combination to these operations.

The functions available for assignment are:

•	Check mail for all - fire off a mail check for all accounts (except those which are explicitly excluded from the "Check all accounts" command.

•	Send queued mail from all - send any queued mail from all accounts.

•	Fetch new mail for the current - fetch mail for the current account.

•	Send queued mail from the current - send any queued mail from the current account.

•	Tray Restore/Minimise - bring The Bat! up out of the system tool-tray if it has been minimised to there. Minimise The Bat! to the system tool-tray if it is currently on-screen.

•	Address Book - Open The Bat!'s address book.

•	New Message - Create a new message from the current account.

•	Open MailTicker ™ messages - If the MailTicker ™ is currently visible, open the MailTicker ™ virtual folder to review all new messages.

•	Invoke SmartBat™  - opens the SmartBat™ so you can access your notes in there or manage your schedule.

Note: if you want to move a hot key from one event to another, you must remove it from the first event. You must then exit the edit dialog using the "Ok" button to store the change. Open the dialog box again and then you can freely assign that keystroke to another event.


Changing keyboard shortcuts

The Shortcut Editor is available in most of The Bat!'s non-modal windows (such as main window, separate message browser, address book, message editor) - you can invoke it by using the View|Edit Shortcuts menu command of any of such window.

The purpose of the Shortcut Editor is to assign shortcuts (hot keys) to those menu functions you use often and re-define default shortcuts to suit your style of keyboard use. For example, you may want to assign a shortcut for quick accessing the Folder Maintenance Centre or for a specific Quick Template in the message editor or for assigning messages to a particular Colour Group - just open the Shortcut Editor of the window you wish to define the shortcut for, find the corresponding command in the menu tree and use the desired key combinations.

Please note the rules of using shortcuts:

•	You cannot assign a single-letter shortcut for the main menu of the main window - otherwise, you won't be able to type the letter in the message editor and other non-modal windows.

•	You cannot assign the same shortcut to different commands in the same menu

•	Local pop-up menu shortcuts are functional only within the control where the menu belongs to

•	Local menu shortcuts have higher priority than the main menu shortcuts

•	Shortcuts defined for the main menu of the main window can be used in any non-modal window of The Bat! if they are not overriden by Window's own shortcuts

•	Shortcuts are defined in context, meaning that you will only be able to assign shortcuts for use in the editor while using the editor.


Changing appearance of main controls

You may want to change appearance of most controls within The Bat! to suit your taste. By default, all controls use the system default colour scheme.

The following table contains the list of controls that can change their appearance within The Bat!:

Control	Settings	The page of the Options|Preferences dialogue	Notes
Folder tree	Font	System	The default colour is defined by Windows' appearance settings, you may change the colour of a particular folder by assigning it to a particular colour group
Message List	Font	Messages|Colour Groups and Font	The same font is also used for the message list header control
Message Header	Font, Colours, Custom message header fields	Messages|Message Header  and Messages|Header Layout
MicroEd (plain text editor and viewer)	Font and colours	Editor/Viewer|Plain Text/MicroEd	Only fixed width fonts can be used for MicroEd
HTML Viewer and Editor, Windows plain text editor	Fonts and colours	Editor/Viewer| HTML/Windows Editor
Message Source Viewer	Font and colours	Editor/Viewer|Source Viewer
MailTicker	Background colour, font and opacity	Messages|MailTicker


Defining custom actions

It is possible to define complex actions on currently selected messages. To do that, you should create a new filter in the Sorting Office , select actions you wish to perform on a message on the Actions page and define a shortcut on the Options page. The defined set of actions will be executed by using the specified shortcut while a message from the corresponding account is selected.

Please note:

•	if the source and the target folders are different, the message will be moved to the target folder. Conversely, if the folders are the same, the message will not be moved.

•	to prevent automatic execution of a filter (unless it is needed), use the "This rule is executed only by pressing the hot key" option.

•	the action set of an inactive filter (i.e. the Active option is unchecked) won't be executed


Plug-ins

What in fact is a plug-in? Generally speaking it's a small piece of software that enriches a larger piece of software by adding features or functions. The idea behind plug-ins is that a small piece of software is loaded into memory by the larger program, adding a new feature, and that users need only install the few plug-ins that they need, out of a much larger pool of possibilities.

There are many plug-ins for The Bat! in Internet. They can be downloaded and easily connected to The Bat!. To do so press the the 'Add' button and search for it on your HD or over the network. In this section you can also delete, configure and get information about the plug-in.


Protecting your account’s mail with a password
Protecting your account's mail with a password

With The Bat!, you can "lock" your account with a password so nobody can read your mail using The Bat! without your permission. This is often used in the situation where a computer is located in an office where anybody has access to it while the user is away. Do not confuse the account access password with your mail server password - these are two different things so make sure that you use two different passwords for your privacy's sake.

In a multi-user environment, the account access password is also used for logging on.

To protect your account with a password, use the "Account | Set Access Password" menu command or press <Ctrl+F12>. You will be prompted to enter the password you want to use to access your account. If you already have a password set for your account, you can enter an empty string as your password - the account will be unprotected after doing this.

N.B. The use of a password merely restricts access to the User Interface for your messages. The mailbase is not encrypted and is not protected in any other way.


Warning on opening attachments

The Bat! is a e-mail client well protected against viruses, worms and trojans. We offer additional warnings before opening files with certain extensions. It is done on purpose as there can be cases when a file can be opened accidentally.

On the other hand if you are sure you want to open the attached file and not get the warning press SHIFT + double click.

One more convenient feature is the possibility to define certain files extensions as not dangerous. This is particularly useful when you receive messages with attached files from your co-workers or friends.


Using Anti-Virus plug-ins

Currently, e-mail viruses are one of the biggest threats to the Internet community. Even though most Anti-Virus (AV) software vendors allow the checking of incoming messages received by POP3 connections, there are several uncovered issues:

•	only insecure (non-TLS) connections can be monitored

•	AV software has to check any message passing through its filters (while The Bat! may check files only they are saved or executed), thus the process of mail retrieval gets significantly slower, overall system performance may go down

•	PGP/MIME and S/MIME encrypted messages cannot be checked

•	IMAP connections are not monitored in most cases

•	If a virus was received before the AV software has updated its database, there is no way to remove the virus from the message base unless the AV software is familiar with the message base format (if a message base in encrypted, it  is impossible to remove viruses from there anyway)

•	There can be a problem in AV software when several accounts are checked simultaneously (in other words, most AV packages only support one connection at a time).

•	Most AV software requires quite uncomfortable changes to the configuration of e-mail clients

To cover the above issues, The Bat! has introduced an Anti-Virus Plug-in interface.

To start using the Anti-Virus support, you should install one or more of the anti-virus plug-ins. Open the preferences dialog from the Options|Preferences menu and in the preferences tree click on the Anti-Virus leaf. Click the Add button  - you will be prompted to select a .BAV module of the plug-in you wish to install.

To actually use plug-ins check the Check incoming mail for viruses check box.

Send notification to the sender enable this to send a reply to the sender using a template.

Note: Most modern viruses fake the sender's address and it is unlikely that any reply you send will actually go to the individual who's computer was sending out infected messages. Use this option with care, if at all.

Perform this action will allow you to choose one of the following possibilities:

Try to cure infected parts if selected, it will try to repair infected parts of  a message such as attachments. When virus is detected, but it is not possible to remove it without damaging the rest of the file, the file will be removed from the message completely.

Remove infected parts remove only the infected parts of the message, leaving non-infected parts of the message intact.

Forward the message to self use this to forward message to your own address. This may be useful for administrative purposes. It is possible to add accompanying text and change the subject and destination address using Template facilities.

Delete the message

Move to the Quarantine folder moves the infected message to the account's Quarantine folder. The Quarantine folder is automatically created when you receive your first infected message. This may be useful for administrative purposes and avoiding false positives.

Check attachments for viruses before opening them from The Bat! If not checked, it will not perform attachment checking when a user tries to open it from The Bat! preview pane. It is recommended always to keep this option checked.

Check attachments before the user saves them to the disk use this to check for viruses in every message you save to the local disk or network path.

Check outgoing mail for viruses to protect yourself from sending infected messages.


About spam

General Information

If you are not a newcomer to the world of e-mail then you probably know what spam is. Generally speaking it is unwanted messages containing advertisements. You only have to fill in a few forms, write a few articles while actively participating in the internet forums or publish a personal web page and you will start to receive correspondence like that.

How can you tell the difference between a spam message and a business letter?

Business letters usually specify your name, not just your mail box, and spammers do not pay enough attention to find out your real name. Spam offers you items that are usually not in your area of interest and is trying to grab your attention as much as possible before you dump it in the Trash Folder.

Why does spam exist?

Unfortunately some people believe that spam is a good way to advertise using the internet. And there are some people who get caught by these kind of ads. If everyone just deleted the letters, then spam would cease to be a problem for all internet users in a no time. Another reason is that a spammer can easily make himself anonymous, which makes it difficult to determine whether the further messages with ads come from the same source.

How to deal with it?

Whatever happens, it is a bad idea to reply and ask to be removed from this list. Also you can sort your incoming letters by sender's name and subject and delete those you do not want. Another way is to use Anti-spam programs that act as middleware and check all incoming traffic for known signs and so called fingerprints. The Bat! offers an interface for installing self learning anti-spam plug-ins. You can learn how to install and use them with The Bat in the Using Anti-Spam plug-ins topic.


Using Anti-Spam plug-ins

The Bat! offers an interface for installing anti-spam plug-ins. Each message you receive is given a score from 0 to 100 to determine whether or not it is spam, and if the points are above a minimum that you set in preferences it is moved to the Junk Mail Folder. To determine whether or not a message is Junk in The Bat! you can use Mark As Junk and Mark as NOT Junk options from the Specials sub-menu.

In order to use the Anti spam support first you have to install an anti-spam plug-in with self-teaching facilities. To install a plug-in, open the Preferences dialog from the Options | Preferences menu and in the preferences tree click on the Anti-spam leaf.

To add a new plug-in just click on the Add button and in the file dialog browse through the directory tree and choose an appropriate file with a .tbp extension. It will appear in the Anti-spam plug-ins list. For each installed plug-in in the list you will see its name, version, status (Shows how many kilobytes it currently takes in memory. If zero, then it is not currently loaded) and the path to the .tbp file. By selecting a plug-in from the list and clicking on the Configure button you can change the configuration options for the plug-in. Selecting and clicking on Delete will remove the plug-in from the list.

Of 100 score to be used for actions below you can choose between Average, Maximal and Minimal. Different plug-ins have their own scoring system. When you install more than one and get different scores for a message, then by using this option you can determine if you can use a maximal/minimal score between them or the average. For example if Plug-in 1 gives a message a score of 50 points and Plug-in 2 gives it a score of 70, then 70 is used if maximal is checked, 50 for minimum and 60 if average is checked.

Delete a message if the score is greater than determines the minimum amount of points after which a message will be deleted if its score is equal or greater.

Move a message to the Junk folder if the score is greater than determines the minimum amount of points after which a message will be moved to the Junk folder if its score is equal or greater. The Junk folder is created automatically when you get your first junk message.


Secure messaging with OpenPGP

The Bat! is well equipped to use OpenPGP mechanisms to protect your messages from unauthorised reading and/or modification.

Version 2 introduces PGP/MIME support, so it is now possible to send PGP signed/encrypted files without hassle. Also, built-in support for PGP v6-8 is included (please note that this means you should have a copy of PGP installed). The interface for handling signed/encrypted messages is universal – no matter which system (PGP or S/MIME) is used, you can verify or decrypt it with just the press of a single button.

To use PGP v2.6.3 with The Bat!, just install PGP completely, and make sure that the directory in which the PGP executables have been installed is in your system's PATH Environment variable and that the PGPPATH environment variable is set according to the PGP documentation. Please read the documentation on PGP carefully before using it. Outside the U.S., you may download PGP v2.6.3 International. The U.S. version of PGP 2.6.3 is no longer available.

To use PGP v5.5.3 or higher with The Bat!, just install PGP completely and make sure that all of the PGP DLL's can be located through your system's PATH Environment variable. United States and Canada residents may download PGP 5.5.5 (U.S. Export Restricted) from its official Web site. Outside the U.S., you may download PGP 5.5.3 International and the PGP 5.5.5 User's Manual from the International PGP WWW site - http://www.pgpi.com. Versions of PGP later than 6.5.3 may be downloaded from anywhere in the world since US export restrictions were lifted from these versions.

To use GnuPG 1.2.3 or higher with The Bat! just install GnuPG completely, and make sure that the directory in which the GnuPG executables have been installed is in your system's PATH Environment variable.

After you have your version of OpenPGP installed according to the above instructions, you can use secure messaging and OpenPGP functions from the main window's Tools menu and the message editor's Privacy menu.

See also: 	Encrypting your message with OpenPGP

Decrypting OpenPGP signed messages

Signing your message with PGP

Verifying OpenPGP signed messages

Adding OpenPGP public keys from a message


PGP/MIME standard

The term "PGP/MIME" means PGP/Multipurpose Internet Mail Extensions

The PGP/MIME standard provides secure messaging to conform to the following RFCs:

•	RFC1991 PGP Message Exchange Formats

•	RFC2015 MIME Security with Pretty Good Privacy (PGP)

•	RFC2440 OpenPGP Message Format

•	RFC3156 MIME Security with OpenPGP

PGP/MIME allows secure messaging with no hassle because it eliminates problems with sending complex messages (i.e. ones with attachments, using different character sets, etc.) unlike ASCII-armoured OpenPGP messages - the latter method does not provide any straightforward support for character sets, each file attached must be signed/encrypted separately.

Because PGP/MIME supersedes the ASCII-armour format, we chose to use PGP/MIME automatically by default. That means, whenever a messages is about ot be signed/encrypted with OpenPGP, its content is analysed and the most suitable format is chosen. Here is a list of cases when the PGP/MIME format will be used for signing/encryption:

•	a message includes attachments

•	a message is created using HTML or other Rich Text format

•	a non-ASCII character set is used in the message text

•	the message text contains lines longer than 76 characters

•	the message text has lines beginning with "From " (some mail servers may add a symbol at the start destroying the cryptographic integrity of such a message)

•	the message text contains lines with trailing spaces like the standard <dash><dash><space> signature separator (some mail servers may strip trailing spaces destroying the cryptographic integrity of such a message)

To use PGP/MIME for messaging, you should make sure the recipient of your messages is able to process PGP/MIME messages, because there still are mail clients not supporting the format. It's very simple to do by sending one signed and one encrypted message to your correspondent and ask him/her whether the messages were properly delivered and verified/decrypted. For those people you cannot use PGP/MIME with, you may want to create separate address book templates including the %NOPGPMIME macro.

With template Privacy Macros, you can simply choose the standard options to use PGP/MIME in your mesages by default. The macros you can use to affect this are:

•	%AUTOPGPMIME - default option, described above, may be used in Quick Templates

•	%PGPMIME - always use PGP/MIME for the message (some systems may require PGP/MIME because they do not support the ASCII-armoured format)

•	%NOPGPMIME - disable PGP/MIME


Decrypting OpenPGP messages

Whenever you receive an OpenPGP encrypted message, you can decrypt it if you have a properly installed OpenPGP implementation and an appropriate private key in your key database. Please refer to the manual for your OpenPGP implementation for more information on OpenPGP key pairs.

To decrypt an encrypted e-mail message from The Bat!, use the "Check OpenPGP signature" command from the "Tools | Privacy" menu (<Shift+Ctrl+D>). If the message is signed, OpenPGP automatically checks the validity of the signature. Note that the decrypted message is NOT stored so you will need to decrypt it this way each time you need to read the message.

Another way is to decrypt  the message into your message base using "Decrypt OpenPGP..." command of the Tools menu. Note that in this case your privacy might be compromised because the message is stored in your message base in clear text so that anybody else with access to your system can read it.

See also: 	Encrypting your message with OpenPGP

Signing your message with OpenPGP

Verifying OpenPGP signed messages

Adding OpenPGP public keys from a message


Verifying OpenPGP signed messages

Whenever you receive an OpenPGP signed message, you can check whether the signature is valid ensuring that the information in the message has been sent by an authorised person and has not been changed before it arriving in your mailbox. To do this, you should have an OpenPGP implementation properly installed and the sender's public key in your public key database or "keyring".

To verify a signed e-mail message from The Bat!, use the "Tools | OpenPGP | Check OpenPGP signature" command (<Shift+Ctrl+C>). If the message is encrypted, it will be automatically decrypted (the OpenPGP implementation you are using may ask you to enter your passphrase).

N.B.: "Validity" of an OpenPGP key is about whether or not you have signed that key. When verifying a message from a user whose key you have not signed, the signature will show as "Invalid". Once you sign the key with your default key (showing that you are confident in the validity of the key itself) then the signature will show as valid. Only if the signature shows as "Bad" does it mean that the message or signature have been compromised

See also: 	Encrypting your message with OpenPGP

Decrypting OpenPGP signed messages

Signing your message with OpenPGP

Adding OpenPGP public keys from a message


Adding OpenPGP public keys from a message

OpenPGP public keys can be distributed in plain ASCII text and it is therefore possible to embed public key blocks in an e-mail message. Below is an example of a message with embedded public keys.

Hello John,

  This is my public key:

-----BEGIN PGP PUBLIC KEY BLOCK-----

Version: 2.6.3i

mQBtAzPHTM0AAAEDAKCJ5/hM+qpxHaa4wFumqU2DEV4KfkKe5hkkfS6knTtn0rnD

Zm/90txo+29gOFARBL8ynIpGA7fUgmNG13mprN9q/9xrtH4gg6jV/cYJ3ZtnKN9B

sfw7QLKsW3r6eMYGsQAFEbQiU3RlZmFuIFRhbnVya292IDxzdGVmQHJpdGxhYnMu

Y29tPokAdQMFEDPHTM2sW3r6eMYGsQEBft0DAIi04Yya7Q5ZZAtz2K4bKHitMBFV

j1g0Vmr87Cr5qZYgGBzbNasyFwUuFqwqEuiwnLVNSpPiK8QsJTff6Ky9hqMUiZaL

ENOzJ5f9GKw0pmMio7rOlKRE8Szbl6RkpeCUQw==

=u13G

-----END PGP PUBLIC KEY BLOCK-----

All the best,

   Stefan

To import OpenPGP public keys from an e-mail message with The Bat! use the "Import OpenPGP key" command from the "Tools | Privacy" menu.

See also: 	Encrypting your message with OpenPGP

Decrypting OpenPGP signed messages

Signing your message with OpenPGP

Verifying OpenPGP signed messages


Secure messaging with S/MIME

The term "S/MIME" means Secure/MIME, i.e. Secure/Multipurpose Internet Mail Extensions

The S/MIME standard provides secure messaging to conform to the following RFCs:

•	RFC2632 S/MIME Version 3 Certificate Handling

•	RFC2633 S/MIME Version 3 Message Specification

•	RFC2634 Enhanced Security Services for S/MIME

To use S/MIME, you first need to get a "Certificate".

Certificates are small digital documents that confirm that a public key belongs to a specific individual or organisation in a verifiable format. Certificates help to prevent impersonation and fraud.

Certificates are issued by a "CA" or certifying authority. They hold a public key and a name and often an expiration date, the name of the issuing certification authority and a serial number. Most significantly, it contains the digital signature of the issuing CA. The most widely accepted format for certificates is defined by the ITU-T X.509 international standard.

To make sure that certificates are genuine, the public key of the issuing CA used must be known to be trustworthy. To this end, a CA must either publish its public key or provide a certificate from a higher-level CA to ensure the validity of its public key.

A user can get a certificate of their own by generating a key pair and sending the public key to an appropriate CA, perhaps with some proof of their identity. The CA confirms the user's identity and then issues a certificate creating a bond between that user and their public key.

S/MIME Preferences are configured in the dialog that is invoked from the S/MIME item of the Options menu of the main window. There you can select which of the two S/MIME engines should be used: Internal or Microsoft CryptoAPI.

Usually, the process of obtaining of a certificate consists of the following steps:

1. Generate a key pair. In The Bat! with Internal S/MIME Engine, a key pair is generated together with a self-signed certifiate.

2. Create a Certificate-Signing Request and send it to the CA.

3. Receive a certificate from the CA and import it. In The Bat!, the private key from your self-signed certificate will be automatically bound to the certificate that you've received from the CA. You will then be able to delete your self-signed certificate and use one issued by the CA.

Once you have your certificate, you can use it to sign your messages and decrypt messages addressed to you.

See also:

S/MIME Preferences.


Signing your message with S/MIME

To assure your recipients that the messages they receive are really from your e-mail address, it is recommended to sign your messages with an S/MIME signature. S/MIME signed messages contain the original text plus a cryptographic digest compiled using your key information. If somebody tries to modify a message signed by you, the message won't be verified successfully by its end-recipients. S/MIME signing can be used together with encryption.

With The Bat!, you can sign your messages automatically using the on/off "Sign when completed" option of the Privacy menu. You can also enable/disable signing and encryption from message templates by using macros

Unlike OpenPGP, your S/MIME signature usually also contains a copy of your public key so you won't need to make any special effort to distribute your public key.

When you sign a message using S/MIME, the attachements (if any) are also signed.

See also: 	Encrypting your message with S/MIME

Decrypting S/MIME signed messages

Verifying S/MIME signed messages


Encrypting your message with S/MIME

To send messages securely over the Internet, you have the option to encrypt your messages with S/MIME. An S/MIME encrypted message cannot be read by anybody but the people whose public S/MIME keys are used to encrypt the message. S/MIME Encryption can be used together with signing.

Using The Bat!, you can encrypt your messages automatically using the on/off "Encrypt when completed" option of the Privacy menu.

To encrypt your message to a particular recipient, you must have previously imported the recipient's Certificate. Unless you also encrypt to your own default certificate then you will be unable to read the message once it has been encrypted.

When you encrypt a message using S/MIME, the attachements (if any) are also encrypted.

See also: 	Decrypting S/MIME signed messages

Signing your message with S/MIME

Verifying S/MIME signed messages


Decrypting S/MIME messages

Whenever you receive an S/MIME encrypted message, you can easily decrypt it by clicking on the "S/MIME Encrypted Message" icon. When you do this, you will be prompted to enter your secret pass-phrase, which is used to un-shroud your private S/MIME key so that it can be used to decrypt the message.

Once you have done this, the message will be decrypted and presented in a message view window from which you can do the usual things you can do with a received message including Replying to it.

See also: 	Encrypting S/MIME messages

Signing your message with S/MIME

Verifying S/MIME signed messages


S/MIME Preferences

The S/MIME Preferences dialog can be invoked from the S/MIME item of the Options menu of the main window. Use this dialog to select which engine should be used when working with S/MIME: internal implementation or Microsoft CryptoAPI. Whichever engine you will choose, each will have their own configuration options except "Always encrypt to sender's certificate" which is common to both engines.

The Always encrypt to sender's certificate option should be used if you want to be able to decrypt messages that you encrypted when sending. Unless this option is checked, only the recipients of the message are able to decrypt the message - not the sender! 'Recipients' in this context means destination addresses, i.e. e-mail addresses included in "To:", "CC:" or "BCC:" fields.

See also:

S/MIME Preferences - Internal Implementation

S/MIME Preferences - Microsoft CryptoAPI


Internal Implementation
S/MIME Preferences - Internal Implementation

The internal implementation doesn't use any code from outside The Bat!, i.e. doesn't use any of the cryptography or certificate storage components provided by the Microsoft Windows operating system. The main advantages of the internal implementation are reliability, speed and system-independence. It can even be run on such old operating systems as Microsoft Windows 95 or Microsoft Windows NT 3.51 with "NewShell". The certificates and associated private keys are stored in the user's account or address book, making them easy to maintain and backup. System-independence allows you to use the strongest, commercial-grade key sizes for encryption algorithms: RC2 (128bits), 3DES(156 bits), IDEA (128 bits) and RSA (up to 1024 bits). The use of IDEA conforms to RFC-3058. Another advantage of the internal implementation is that it provides data compression before encryption.

The disadvantage of the internal implementation is a lack of flexibility: when it comes to using different third-party algorithms, storage media, or devices that perform certain operations at a hardware level, you will need to use the CryptoAPI engine, but it may work differently or with some limitations under different versions of Microsoft Windows.

Compress data before encryption option states whether the content (message text with attachments, if any) should be compressed by the internal implementation before encryption.

Cache certificate passphrases/keys for option affects whether the passphrases for your S/MIME certificates will be cached by the internal implementation in memory and for how long.

Encryption Algorithm combo-box allows you to choose which algorithm should be used by the internal implementation for encryption.

Signing Hash Algorithm specifies which hash algorithm should be used by the internal implementation for digital signatures. SHA-1, the default setting, should be used in most cases. MD-5 should not generally be used because weaknesses have been discovered in this algorithm that can affect digital signatures; however in some (very rare) cases it may be the only hash algorithm supported by the recipient. MD-5 is faster than SHA-1, but the difference shouldn't be noticeable.

Random Seed File specifies the path where intermediary random data for the internal implementation is  stored. This data is used to generate random session keys and shouldn't be exposed. If your computer is part of a network, please take the appropriate steps to prevent the data in this file from being visible to others. Even if you are accessing The Bat! executable and data files over the network, it is better to keep the random seed file on a local drive to prevent the data from being transferred over a network where it can be intercepted.

See also:

Data compression by the internal implementation

Encryption algorithms used by the internal implementation

Passphrase caching by the internal implementation


Cache Certificate Passphrases

Cache certificate passphrases/keys for option in the S/MIME preferences dialog affects whether the passphrases for your S/MIME certificates will be cached in memory and for how long. This feature is only available when the Internal Implementation is activated in S/MIME Preferences dialog.

If this option is enabled the passphrase for certificates will be cached for the next N minutes after the certificate has been used for a certain operation. Passphrases will be cached separately for four different operations: signature, decryption, private key unshrouding (when a key is being exported to a file without protection) and CSR generation. After signing a message, The Bat! won't ask for the passphrase for subsequent signatures, but will prompt you for it if you want to decrypt a message e.g. Each subsequent operation resets the timer and as long as you continuously use the certificate, you won't need to re-enter the passphrase. If you cease using the certificate for more than N minutes, you will be prompted for the passphrase again.

The cache only exists in memory and is not stored to a hard drive. Thus if you exit The Bat!, the cache will be cleared.


Compress Data Before Encryption
Compress Data Before Encryption (Internal Implementation)

Compress data before encryption option of the S/MIME Preferences dialog governs whether the content (message text with attachments, if any) should be compressed before encryption. This feature is only available when the Internal Implementation is activated in S/MIME Preferences dialog.

This option doesn't affect messages that are signed but not encrypted. Compression reduces message size and makes the message more resistant to attacks. If you are compressing data that is already compressed (e.g. this option is turned on when encrypting a message containing a .ZIP-attachment), this option  may slightly slow down the process. Otherwise, it can make things even faster because encryption algorithms are typically slower than compression algorithms, and after compression less data has to be encrypted.  S/MIME compression, however, is not yet widely adopted and may not be supported by other S/MIME-enabled e-mail clients - even if your recipient uses The Bat! with the CryptoAPI engine for S/MIME. The format of compression conforms to "Compressed Data Content Type for Cryptographic Message Syntax" RFC-3274 by Peter Gutmann.


Encryption Algorithm
Encryption Algorithm (Internal Implementation)

Encryption Algorithm combo-box in S/MIME preferences dialog allows you to choose which algorithm should be used by the internal implementation for encryption: RC2 (128bits), 3DES(156 bits) or IDEA (128 bits). All of these algorithms have similar strength, but RC2 (default setting) is the fastest. The IDEA algorithm is not in widespread use for S/MIME due to patent restrictions and may not be supported by your recipients unless you work in an organisation that already uses IDEA as a corporate standard. IDEA(tm) is patented in the following countries: Austria, France, Germany, Italy, Netherlands, Spain, Sweden, Switzerland, United Kingdom, United States. A license must be purchased from MediaCrypt AG for any use of IDEA(tm) for commercial purposes in the above countries. MediaCrypt AG contact details are: MediaCrypt AG, Technoparkstrasse 1, 8005 Zurich (Switzerland); Tel.: +41-1-445 3070; Fax: +41-1-445 3071; http://www.mediacrypt.com/; mailto:info@mediacrypt.com.

For each message, a unique randomly chosen encryption key (session key) for RC2, 3DES or IDEA is used by the internal implementation to encrypt the message content with attachments, if any. The key itself is encrypted with the RSA algorithm using a public key from the recipient's certificate. The encrypted key comes along with an encrypted message. If the message has multiple recipients or you've chosen to Always encrypt to sender's certificate, the session key is encrypted by RSA for each recipient in parallel and the encrypted message contains multiple instances of the encrypted session key. Thus, there is no advantage in using recipient certificates with strong, large RSA public keys (e.g. 2048-4096 bits) to protect a message when it is also addressed to a recipient with the weaker, short RSA public keys (e.g. 512 bits), because it only takes breaking the weak key to expose the entire message.


Microsoft CryptoAPI
S/MIME Preferences - Microsoft CryptoAPI

If you choose Microsoft CryptoAPI to be your preferred S/MIME engine , The Bat! will use the capabilities provided by Microsoft Windows. Certificate store functions and S/MIME message handling lays within the CryptoAPI core while actual cryptography and private key storage will be done by Cryptographic Service Providers (CSPs). The Bat!, however, doesn't call the Cryptographic Service Providers directly, but uses the CryptoAPI interface to enumerate available CSPs and work with a CSP. The Certificate Manager, which can be called from Microsoft Internet Explorer (Tools | Internet Options | Content | Certificates) can be used to view, import, export and delete certificates while working with CryptoAPI. CryptoAPI is not supported under Windows NT 3.51. Under Windows 95, you should install Internet Explorer 5 or higher because it contains the CryptoAPI redistributable files that are missing from the original Windows 95 installation. Under Windows NT 4.0 you should also install Microsoft Internet Explorer 5 or higher and Service Pack 4 or higher. However, under Windows 95 and NT 4.0 some limitations will remain, even after installing the redistributable components. Other versions of Microsoft Windows (98, ME, 2000, XP and future versions) are already equipped with CryptoAPI and do not need any additional  software.

Please note that CryptoAPI doesn't support data compression.

Cryptographic Service Provider combo-box enumerates all available Cryptographic Service Providers. If you choose a provider from the list, The Bat! will limit itself to the use of the selected provider only and other providers won't be used. If "<default>" is selected, CryptoAPI will dynamically select the required providers corresponding to a particular algorithm, key type or certificate.

It's best  to leave the provider set to default unless there are very strict security requirements and it is forbidden to pass control to a CSP other than the selected one. Please note that if you select a provider and, for instance, need to verify a message signed using a certificate which isn't supported by the selected CSP (or you need to encrypt a message to a recipient that has a certificate which isn't supported by the selected CSP), the operation will fail, even though a CSP supporting that certificate may exist in your system.

Under Windows 95 and NT 4.0, enumeration of available CPSs isn't supported. Microsoft Internet Explorer 6 or NT 4.0 Service Pack 6a doesn't contain redistributable code allowing the listing of CSPs. Thus you won't be able to limit The Bat! to use a particular CSPs. It will use a suitable CSP for particular algorithms from all currently installed CSPs.

Encryption Algorithm combo-box allows you to choose which algorithm should be used by CryptoAPI for encryption. The list of available algorithms is taken from the currently selected CSPs. The combo-box only appears if you select a CSP other than <default>. The way the selected algorithm is handled depends on each particular CSP. The choice only affects encryption. It doesn't affect decryption, signing or signature verification.

Signing Hash combo-box allows you to choose which algorithm should be used by CryptoAPI for digital signatures. The list of available algorithms is taken from the currently selected CSPs. The combo-box only appears if you select a CSP other than <default>. The choice only affects signature operation when you sign your messages. It doesn't affect encryption, decryption or signature verification.

When working via CryptoAPI, The Bat! can only add one signature to a message, i.e. a message cannot have multiple signers. But it can have multiple recipients. When signing a message, the first address is taken from the "From:" field as the signer's address. If the "From:" field is empty or doesn't  contain a valid address, the contents of the "Reply-To:" field is taken instead. Then the system's "MY" certificate store (which usually consists of certificates visible under the "Personal" and "Other People" tabs of the Certificate Manager) is looked at to retrieve the first valid certificate issued for this e-mail address. The certificate should also contain a private key.

When encrypting a message to multiple recipients using CryptoAPI, a valid certificate will be retrieved for each recipient. First, the "MY" system store is searched. If no suitable certificates are found in the "MY", The Bat! searches the "CA" system store. The "MY" system store usually contains certificates that are visible under the "Personal" and "Other People" tabs of the Certificate Manager; and the "CA" store contains certificates from the "Intermediate Certification Authorities" tab. The reason for looking in "CA" store is that the Certificate Manager may have failed to select the correct store for the certificate being imported if the recipient certificate doesn't have a Basic Constraints extension,  - and has put the certificate under "Intermediate Certification Authorities" rather than "Other People". Different recipients can have different kinds of certificates, and the message is encrypted in parallel using all the certificates. Thus, there is no advantage in using recipient certificates with strong certificates having large public keys to protect a message that is also addressed to a recipient with weak certificates with short public keys, because it only takes breaking the weak key to expose the entire message.

Whether a recipient has multiple certificates or only one certificate in the certificate store, you'll be asked which certificate should be used for a particular e-mail. Even if a recipient has only one certificate, you should  be able to view the certificate used for encryption. Same for signatures, you will be prompted which of the certificates should be used to sign your messages. Only valid certificates can be used for signatures/encryption.

If you've checked the Keep associations between e-mail addresses and certificates for signing option, The Bat! will remember which certificate has been used to encrypt a message to a particular e-mail. If you've checked Keep associations between  e-mail addresses and certificates for encryption option, The Bat! will remember which certificate has been used to sign a message from a particular e-mail. The Bat! stores this association information on your hard disk and each mail account has own separate associations.


S/MIME Certificate Manager

The S/MIME Certificate Manager is a special tab of the "Edit Address Entry" dialog box. This tab is only available when the Internal Implementation is activated in S/MIME Preferences dialog.

The list contains the S/MIME certificates associated with the selected address entry. There are distinguishing glyphs to show you whether a particular certificates has a private key. The validity status isn't shown in the list. Just double-click a particular certificate or click the View button to verify the certificate.

You can perform the following actions with the certificates:

Import certificates from files

Export selected certificates

View the focused certificate

Delete selected certificates

Generate a self-signed certificate

Perform a certificate signing Request


Import S/MIME Certificate

If you have received certificates from other S/MIME users then you can import them into the Address Book entry by right clicking on an attached certificate icon and choosing "Import key or certificate" from the context menu.

This feature is only available when the Internal Implementation is activated in S/MIME Preferences dialog.

You can also use the "Import" button on the Certificates tab of the entry's properties to import an external certificate data file.

A certificate can also be imported when you are viewing it. Just click the "Add to Address Book" button on the "General" tab of a certificate viewer window.

The Bat! supports the following formats when importing certificates: Personal Information Exchange - PKCS #12 (developed by RSA Laboratories), Cryptographic Message Syntax Standard - PKCS #7 (conforming to RFC-2630), Netscape Certificate Sequence (proprietary Netscape format), DER-encoded X.509 certificate and PKCS#1 DER-encoded RSA private key. Both binary and Base64-encoded representations are supported for all of the above formats. You can select multiple files in a file open dialog. If you are importing a private key and there is a certificate corresponding to this key, the key will be automatically associated with the certificate. Otherwise, the key will be ignored.


Generate Self-Signed S/MIME Certificate

The Bat! gives you an ability to generate a self-signed certificate with the corresponding private key.

This feature is only available when the Internal Implementation is activated in the S/MIME Preferences dialog.

This certificate will not be trusted by your recipients since it's not signed by a Certification Authority (CA), but you will be able to derive a Certificate Signing Request (CSR) from this self-signed certificate. Then you can send the CSR to a CA to obtain a regular certificate signed by the CA and trusted by all of the recipients who trust the CA

The main reason for generating self-signed certificates is to have a temporary storage for a private key until you receive a certificate signed by a CA. The certificate, however, can be used for digital signatures and encryption. You will only need your recipients to add it to the Trusted Root CA address book. But the use of self-signed certificates for communication is not recommended.

During the certificate generation process, The Bat! will go through the following steps:

Make you choose which pieces of information should be included into the certificate

Ask you to select the RSA key size

Prompt for a passphrase to shroud the private key


Create a Certificate Signing Request

The Bat! has the ability to generate Certificate Signing Request (CSR) files, conforming to PKCS #10 (RFC- 2314).

This feature is only available when the Internal Implementation is activated in the S/MIME Preferences dialog.

You can use this feature to either request new certificates or to extend your existing certificates that are about to expire. The CSR has to be delivered to a CA. Some CAs may only require a CSR to be sent them for certificate issuance, not for extension.

Each CA has their own terms of expiration for issued certificates, but the PKCS#10 format of CSRs is supported by most CAs. Different CAs may, however, set their own rules as to how the CSRs should be delivered to them.

Upon receipt of a CSR, a CA should issue a certificate for you, according to the information contained in the CSR. The way the information is verified also depends on the CA.

You can create a CSR from any certificate that has an associated private key, because a CSR contains a digital signature. Just select the certificate in the certificate list (from the "Certificates" tab of your address entry (vCard)) and press the "Request" button. You will be prompted for the passphrase. If Cache certificate passphrases/keys option is on, the passphrase will be cached for subsequent occurrences of generating Certificate Signing Requests from this certificate.

As soon as you receive a new certificate from the CA, just import it. The private key from the old certificate will automatically be bound to the new certificate. Then you can delete the old certificate unless you have already distributed it (and it hasn't yet expired). If someone has your (still valid) certificate but you've deleted it, he or she could send you an encrypted message and you'll be unable to decrypt it.


About The Bat! Command line parameters

The command line is a text string that is passed to the system whenever any program is executed; it contains the path to the program with a following set of parameters. In Windows, you can start a program using the Start Menu "Run..." command or by clicking on a Shortcut on the Desktop or in the Start menu. If you start a program by clicking a Shortcut, you can edit the command line for the program in Shortcut Properties' "Target" input box.

For The Bat!, the Command Line in a Shortcut usually looks like this:

"C:\Program Files\The Bat!\TheBat.EXE"

You can add some start-up parameters to it to define a set of actions performed whenever you open the Shortcut. For example, if the Shortcut is located in the Windows Startup folder, you may want to switch off the The Bat! startup Logo by adding the /NOLOGO parameter, so the "Target" property of the shortcut becomes something like this:

"C:\Program Files\The Bat!\TheBat.EXE" /NOLOGO

We have implemented a set of Command Line parameters (we call them commands) that help you to perform actions within The Bat! without having to do so manually, making it is possible to use The Bat! from batch files or other programs as an e-mail transport without having to know details of Internet mailing and to perform scheduled tasks automatically (for example, checking for new mail at a particular time and then exiting so The Bat! would not use your system's resources for too long a time).

Note that you can run only one copy of The Bat! on your PC at one time, but if you try to start another copy of The Bat!, all Command Line parameters will be seamlessly passed to the running copy of the program and executed.

For those who are familiar with programming, here's a handy hint: The Bat! checks a file called TheBat.IPC which is located in the same directory in which The Bat! executable (TheBat.exe) file is located. Within this text file, each line represents one command that can be executed by the program, so you can write commands to this file directly and control The Bat! on your PC even over a local network. Note that TheBat.IPC is deleted as soon as all commands from it have been executed, so if this file does not exist, you will have to create it to make use of it.

To ensure that a copy of The Bat! is running on a computer, a program that need to interact with The Bat! must check whether the mutex called "The Bat!" is owned by a process and, if it is not, The Bat! must be started.


Checking for new mail - /CHECK and /CHECKALL commands

/CHECK can be used as a command line parameter for The Bat! whenever you want to check mail for one or more accounts.

/CHECKALL command is used for checking mail for all accounts and exiting from The Bat! if there were no new messages received. It is a shortcut for the combination of /CHECK* /SMARTEXIT

The syntax of the /CHECK command is:

/CHECK<account mask1>[;account mask2[;account mask3[...]]]

The Account mask is used to identify which account(s) to perform the check operation for. It can be:

•	the full name of a single account. Example: /CHECK"My account 1";"My account 2". This instructs The Bat! to check new mail for two accounts with names "My account 1" and "My account 2" (note that quotation marks are not included into accounts' names - they are used only because the names contain space characters)

•	the beginning of a name ending with an asterisk. Example: to check new mail for all accounts with names starting with the word "My", use /CHECKmy*

•	asterisk followed by the end of an account name. Example: /CHECK*1 will check new mail for all accounts with names ending with "1".

•	a name fragment surrounded by asterisks. Example: /CHECK*account* to check all accounts with the word "account" in their name.

•	an asterisk, which means that all accounts will be checked

Notes:

•	To separate account masks, use semicolons (";" character). Do not use spaces between account masks when using the /CHECK command as a command line parameter because a space-separated mask will be interpreted as the start of the next command line parameter and will not be processed as intended.

•	If a mask contains space characters, enclose it in quotation marks as shown in the first example. If a mask contains quotation marks, you should use single quotes (" ' " characters).


Sending queued mail - /SEND and /SENDALL commands

/SEND can be used as a command line parameter for The Bat! whenever you want to send all queued mail from one or more accounts.

/SENDALL command is used for sending queued mail from all accounts and exiting from The Bat! if there were no new messages received. It is a shortcut for the combination of /SEND* /SMARTEXIT

The syntax of /SEND command is:

/SEND<account mask1>[;account mask2[;account mask3[...]]]

The account mask is used to identify the account(s) to perform the send operation for. It can be:

•	the full name of a single account. Example: /SEND"My account 1";"My account 2". This instructs The Bat! to send queued mail from two accounts with names "My account 1" and "My account 2" (note that quotation marks are not included into accounts' names - they are used only because the names contain space characters)

•	the beginning of a name ending with an asterisk. Example: to send queued mail from all accounts with names starting with the word "My", use /SENDmy*

•	asterisk followed by the end of an account name. Example: /SEND*1 will send queued mail from all accounts with names ending with "1".

•	a name fragment surrounded by asterisks. Example: /SEND*account* to send mail from all accounts with the word "account" in their name.

•	an asterisk, which means that queued mail will be sent from all accounts

Notes:

•	To separate account masks, use semicolons (";" characters). Do not use spaces between account masks when using the /SEND command as a command line parameter because a space-separated mask will be interpreted as the start of the next command line parameter and will not be processed as intended.

•	If a mask contains space characters, enclose it in quotation marks as shown in the first example. If a mask contains quotation marks, you should use single quotes ("' " characters).


Import messages - /IMPORT command

The /IMPORT command allows for the batch import of e-mail messages to a specified folder from multiple RFC-822 message files or from UNIX mailbox files. The syntax of the /IMPORT command is:

/IMPORT[parameter1[;parameter2[;parameter3[...]]]

Possible parameters are (a parameter may be identified by two or more names):

USER=value or U=value	value is the name of the destination account. If no FOLDER parameter is specified, the destination folder will be the Inbox of the given account.
PASSWORD=value or P=value	value is the password which will unlock the account if it is needed.
FOLDER=value or F=value	value is the destination folder's pathname. If the pathname does not include an account name, The Bat! will search all accounts for a folder with a matching name; the first folder found will be used as the destination folder. If the specified folder is not found, the Inbox folder of the destination account is used.
UNIX or X	this parameter tells The Bat! that the input files are in UNIX mailbox format. By default, input files are treated as separate RFC-822 messages.
READ or R	when this parameter is used, all imported messages will be marked as read. By default, all imported messages are marked unread.
FILE=value or IN=value or  INFILE=value or I=value	value is a file mask with the pathname for the input files. The /IMPORT command can have an unlimited number of FILE parameters.
DELETE or DEL or W	if this parameter is specified, all files processed will be deleted once they have been successfully imported

Examples of the use of the /IMPORT command:

/IMPORTU="My account 1";FOLDER="Friends and relatives\Sam";IN=C:\InFiles\Sam\*.MSG

/IMPORTF="\\My account 1\Business\Unsorted";UNIX;FILE=C:\InFiles\Unsorted\*.mbx;READ

Notes:

•	To separate parameters, use semicolons (";" characters). Do not put spaces between parameters when using the /IMPORT command from the command line because a space-separated mask will be interpreted as the next command line parameter and will not be processed as intended.

•	If a parameter value contains space characters, enclose it in quotation marks. If a value contains quotation marks, you should use single quotes (" ' " characters).


Export messages - /EXPORT command
Export messages or addresses - /EXPORT command

The /EXPORT command allows the batch export of e-mail messages from a specified folder to multiple RFC-822 message files or to UNIX mailbox files. This command also allows the export of address book entries if the LDIF parameter is specified. The syntax of the /EXPORT command is:

/EXPORT[parameter1[;parameter2[;parameter3[...]]]

Possible parameters are (a parameter may be identified by two or more names):

USER=value or U=value	value is the name of the source account. If no FOLDER parameter is specified, the source folder will be the Inbox of the given account.
PASSWORD=value or P=value	value is the password which will unlock the account if it is needed.
FOLDER=value or F=value	value is the source folder's pathname. If the pathname does not include an account name, The Bat! will search all accounts for a folder with a matching name; the first folder found will be used as the source folder. If the specified folder is not found, the Inbox folder of the source account is used.
DIR=value or D=value or OUT=value or O=value	value is the pathname for the output directory (for RFC-882 messages) or for the output path and file name (for UNIX mailbox). If RFC-822 format is chosen, the exported messages are stored in the output directory in files sequentially named xxxxxxxx.MSG (each "x" character corresponds to a digit from 0 to 9). When the export starts, The Bat! calculates the starting xxxxxxxx number by searching the output directory for the files with names in the same format and, in the case where such files are found, the output file names will begin immediately after the greatest number found. For example, if file 00001234.MSG was in the output directory, the first exported message will be named 00001235.MSG.
UNIX or X	this parameter tells The Bat! that the output file will be in UNIX mailbox format. In this case, the DIR parameter specifies the name of the output file. By default, output files are in RFC-822 message format.
READ or R	when this parameter is used, only read messages are exported. By default, all read and unread messages are exported.
UNREAD or N	when this parameter is used, only unread messages are exported.
REPLIED or RE	when this parameter is used, only replied messages are exported. By default, all replied and non-replied messages are exported.
UNREPLIED or NR	when this parameter is used, only non-replied messages are exported.
PARKED or PR	when this parameter is used, only parked messages are exported. By default, all parked and non-parked messages are exported.
UNPARKED or UP	when this parameter is used, only non-parked messages are exported.
MAXAGE=value or  AGE=value or A=value	value specifies the maximum age (in days) of messages to be exported. If the age of a message exceeds the specified maximum age, the message will not be exported. By default the maximum age is not limited.
START=value or S=value	value specifies the number of the starting message in the source folder. All messages located before the starting message will not be exported. If a negative value is given, the starting message number is calculated by subtracting the positive value from the number of messages in a folder, for example, if -5 is specified, that means that the export will start from the fifth message from the end of the message base.
END=value or E=value	value specifies the number of the final message in the source folder for the export operation. All messages located after this final message will not be exported. If a negative value is given, the last message number is calculated by subtracting the positive value from the number of messages in the folder, for example, if a value of -2 is given, this means that the export will end at the second message from the end of the message base.
OVERRIDE or V	(only used when either the UNIX or the LDIF parameter has been specified) if this parameter is specified, The Bat! will overwrite the output file when it already exists. By default, The Bat! will add new messages to the end of the mailbox file.
DELETE or DEL or W	if this parameter is specified, all messages processed will be deleted at the end of a successful export operation.
LDIF	if this parameter is specified, an address export will be performed. The OUTPUT parameter specifies the name of an output file that will receive exported data in LDIF format.
ADDRESSBOOK=value or  AB=value or BOOK=value	(only for use with the LDIF parameter) value specifies a name, filename or the full path of the address book which is to be exported. If no address book is specified, The Bat! will use the default address book.
GROUP=value or G=value	(only for use with the LDIF parameter) value specifies the handle of the address group which is to be exported. If no address book is explicitly specified, The Bat! will search all address books for the first group whose name matches the specified handle.

Examples of the /EXPORT command:

/EXPORTU="My account 1";F="Friends\Sam";DIR=C:\InFiles\Sam\;S=-20

/EXPORTF="\\Account1\Business\Unsorted";UNIX;O=C:\InFiles\Unsorted\Mail.mbx;UNREAD

/EXPORTLDIF;AB="My Book";Group="My Group";O="C:\MyGroupFile.LDIF"

/EXPORTLDIF;Group="My Test Group";O="C:\MyTestGroup.LDIF"

Notes:

•	To separate parameters, use semicolons (";" characters). Do not put spaces between parameters when using the /EXPORT command from the command line because a space-separated mask will be interpreted as the next command line parameter and will not be processed as intended.

•	If a parameter value contains space characters, enclose it in quotation marks. If a value contains quotation marks, you should use single quotes (" ' " characters).


Focusing a folder - /FOCUS command

The /FOCUS command allows you to automatically focus a specified folder in the main window. This command is especially useful at the program's startup. The syntax of the /FOCUS command is:

/FOCUS[parameter1[;parameter2[;parameter3[...]]]

Acceptable parameters are (a parameter may be identified by two or more names):

USER=value or U=value	value is the name of the source account. If no FOLDER parameter is specified, the target folder will be the Inbox of the given account.
PASSWORD=value or P=value	value is the password which will unlock the account if it is needed.
FOLDER=value or F=value	value is the target folder's pathname. If the pathname does not include an account name, The Bat! will search all accounts for a folder with a matching name; the first folder found will be used as the target folder. If the specified folder is not found, the Inbox folder of the target account is used.
Examples of the /FOCUS command:

/FOCUSU="My account 1";F="Friends\Sam"

/FocusF="\\MyAccount\New mail";P=mypass

Notes:

•	To separate parameters, use semicolons (";" characters). Do not put spaces between parameters when using the /FOCUS command from the command line because a space-separated mask will be interpreted as the next command line parameter and will not be processed as intended.

•	If a parameter value contains space characters, enclose it in quotation marks. If a value contains quotation marks, you should use single quotes (" ' " characters).


Automated message creation - /MAIL command

The /MAIL command is used for automated message creation using a template, text file and/or set of attached files for a specific destination address. This command is extremely useful for applications that need to send e-mail messages without having to do the additional work involved in the implementation of the various Internet email standards. The syntax of the /MAIL command is:

/MAIL[parameter1[;parameter2[;parameter3[...]]]

Possible parameters are (a parameter may be identified by two or more names):

USER=value or U=value	value is the name of the source account. If no FOLDER parameter is specified, the target folder will be the Inbox of the given account.
PASSWORD=value or P=value	value is the password which will unlock the account if it is needed.
FOLDER=value or F=value	value is the target folder's pathname. If the pathname does not include an account name, The Bat! will search all accounts for a folder with a matching name; the first folder found will be used as the target folder. If the specified folder is not found, the Outbox folder of the target account is used.
TEMPLATE=value or T=value	value is the pathname of the file which contains the template that will be used for the creation of the message. By default, it is the standard template of the target folder or the target account.
TO=value	value specifies the primary addressee of the message. You can add additional addressees using template macros %TO, %CC, %BCC.
SUBJECT=value or S=value	value specifies the subject of the message. It is also possible to define the message subject in the template using %SUBJECT macros.
TEXT=value or  CONTENTS=value or C=value	value is the pathname of a plain text file which contains the text of the message. It is also possible to include a text file into a message using the %PUT macro in the template.
ATTACH=value or  FILE=value or A=value	value is the pathname of the file which will be attached to the message. It is also possible to use %ATTACHFILE macros in the template.
SEND	if this parameter is used, the created message will be sent out as soon as it has been created.
QUEUE	if this parameter is used, the created message will be queued in the Outbox once it is created.
EDIT	if this parameter is used, The Bat! opens the editor with the message created using the parameters from above
Examples of the /MAIL command:

/MAILU=MyAccount;TO=some@address.com;S=Test;TEXT=C:\TESTs\TEST.MSG

/MAILF=\\MyAccount\Test;TO=some@address.com

Notes:

•	To separate parameters, use semicolons (";" characters). Do not put spaces between parameters when using the  /EXPORT command from the command line because a space-separated mask will be interpreted as the next command line parameter and will not be processed as intended.

•	If a parameter value contains space characters, enclose it in quotation marks. If a value contains quotation marks, you should use single quotes (" ' " characters).


Interactive message creating - mailto: command
Interactive message creation - mailto: command

The mailto: command is used to force The Bat! to open a new editor window using pre-set parameters. mailto: is a standard Internet URL for publishing e-mail addresses and is described in RFC 2368. This command line parameter is usually used by browsers which need to open an e-mail editor when the user clicks on a link which contains a mailto: URL.


Adding a new account - /ADD command

Syntax:

/ADD;Parameters

Possible parameters are:

User="account name"	specifies the account's name
InServer="POP/IMAP server address"	specifies the Incoming Mail server address
OutServer="SMTP server address"	specifies the Outgoing Mail (SMTP) server address
InUser="POP/IMAP login user"	specifies the user name at the Incoming Mail server
Password="POP/IMAP login password"	specifies the password at the Incoming Mail server
OutUser="User name for SMTP authentication"	specifies the user name at the Outgoing Mail server (if it differs from the user name specified for the Incoming Mail server).
OutPassword="Password for SMTP authentication"	specifies the password at the Outgoing Mail server (if it differs from the password specified for the Incoming Mail server).
Combined	use if the send+receive option should be activated
Deferred	use if deferred delivery should be used by default
IMAP	use if IMAP protocol should be used for this account
FileDir[="attachment directory"]	use if attachments should be stored separately.
Template="New message template file"	specifies the default new message template for this account located in a disk file.
ReplyTemplate="Reply message template file"	specifies the default reply template for this account located in a disk file.
ForwardTemplate="Forward message template file"	specifies the default forward template for this account located in a disk file.
KeepDays=N	use to limit the time messages are kept on the server
DelReceived	use to activate message deletion right after they are received from the server
FromAddr="FROM email address"	specifies the FROM email address for this account.
FromName="FROM name"	specifies the FROM name for this account.
ReplyAddr="REPLY-TO email address"	specifies the REPLY-TO email address for this account (if it differs from the FROM address).
ReplyName="REPLY-TO name"	specifies the REPLY-TO name for this account.
DelTrashServer	use to delete messages from the server if they are deleted from the Trash folder
SizeLimit=<N K bytes>	use if the size of received messages should be limited to N K Bytes
PortPOP=N	specifies a non-standard POP port for the account
PortSMTP=N	specifies a non-standard SMTP port for the account
PortIMAP=N	specifies a non-standard IMAP port for the account


Execution of multiple commands from a file - /BATCH command

If you need to execute a lot of commands many times, the /BATCH command is  a life saver. This command allows the execution of multiple commands defined in a text file; each command being placed in one line. The syntax of the /BATCH command is:

/BATCH:<filepath>

For example, if you have to check your account and send queued mail from it, you can create a batch file called C:\The Bat!\CheckMail.BAT which contains three lines:

/CHECKMyAccount

/SENDMyAccount

/SMARTEXIT

To execute this batch file from a command line, you can run The Bat! with the command line parameter

/BATCH:"C:\The Bat!\CheckMail.BAT"

Notes:

•	If a parameter value contains space characters, enclose it in quotation marks. If a value contains quotation marks, you should use single quotes (" ' " characters).


Miscellaneous commands - /MINIMIZE, /EXIT, /SMARTEXIT and /NOLOGO

All of the commands below can be passed to The Bat! at the program's start-up or during its operation.

The /EXIT command is used to force The Bat! to exit as soon as all mail transfer operations are complete.

The /SMARTEXIT command is used to force The Bat! to exit as soon as all mail transfer operations are finished but only if there were no new messages received.

The /MINIMIZE command forces The Bat! to minimise. If the "Minimize to tray" option is in force, then The Bat! will minimize to the tool tray and disappear from the Windows ™ task bar.

The /NOLOGO command can be used only during the start-up of The Bat!. When it is used in the program's start-up command line, The Bat! Logo screen will not be displayed while program is loading its data. This feature can be used when The Bat! is automatically run at your system's start-up.


What are Regular expressions?

Regular expression matching allows you to test whether a string fits a specific syntactic shape. You can also search a text string for a sub-string that fits a pattern.

A regular expression describes a set of strings. The simplest case is one that describes a particular string; for example, the string foo when regarded as a regular expression matches foo and nothing else. Nontrivial regular expressions use special constructs with which they can match more than one string. For example, the regular expression foo|bar matches either the string foo or the string bar; the regular expression c[ad]*r matches any of the strings cr, car, cdr, caar, cadddar and all other such strings with any number of a's and d's.

The Bat! allows the use of regular expressions in these places:

Message Editor

Message Finder

Sorting Office / Filters

Templates

To learn about Regular Expressions, you can read the following topics:

Regular Expressions Syntax (Basic)

Regular Expressions Syntax (Advanced)


Using Regular Expressions in the Message Editor
Using Regular Expressions in the Message Editor/Viewer

In the message editor/viewer, regular expressions can be used to search for sub-strings matching a search pattern. To find a sub-string that matches a regular expression, invoke the search dialog and type the regular expression, make sure that the "Regular Expressions" checkbox is checked and start the search. Regular expressions can also be used for the Replace function in the Message Editor in the same way as they are used in the search dialog.

If a match is found, the text that matches the given regular expression will be marked as selected in the message editor/viewer. If the regular expression has subpatterns, the first captured substring will be selected, i.e for the regular expression Total amount: *(\S+) only the word following Total amount will be selected but not Total amount itself.

The default PCRE options for the message editor/viewer are PCRE_CASELESS or none for a "Case sensitive" search. Matching is done on a String-by-string basis.

See also:

Regular Expressions Syntax (Basic).

Regular Expressions Syntax (Advanced).

Message Editor.


Using Regular Expressions in the Message Finder

To make the Message Finder use regular expressions as the search pattern, enter the regular expression you want to use, click to the "Advanced" tab and tick the "Regular expressions" checkbox.

The default PCRE options for the message finder are PCRE_CASELESS+PCRE_MULTILINE or PCRE_MULTILINE for a "Case sensitive search". Matching is done by treating the whole message as a single string. CF/LF pairs (0D/0A) are replaced by single LF (0A) characters before matching.

See also:

Regular Expressions Syntax (Basic)

Regular Expressions Syntax (Advanced)


Using Regular Expressions in Message Filters

It is possible to use Regular Expressions as signal strings in the message filters. In a filter definition in the Sorting Office dialog, select the "Options" tab and tick the "Regular expressions" checkbox. Note that ALL signal strings of the filter will be treated as regular expressions so make sure that they all comply with Regular Expression syntax.

The default PCRE options for message filters are PCRE_CASELESS+PCRE_MULTILINE. Matching is done by treating the whole message as one string. CF/LF pairs (0D/0A) are replaced with single LF (0A) characters before matching.

See also:

Regular Expressions Syntax (Basic).

Regular Expressions Syntax (Advanced).

Message Filters.


Using Regular Expressions in Templates

The Bat! allows full access to the power of regular expressions in message templates. The general idea is to search some text for the first occurrence of a sub-string matching a pattern defined in a regular expression and then to insert the result of that search right back into the message text. For example, it is possible to parse incoming messages of a particular format and create new messages in another format with extra, modified or removed information.

To search the original message text for a sub-string, use the %REGEXPTEXT="regexp" macro where regexp defines the search pattern. The %REGEXPQUOTES="regexp" macro does the same, but returns the result pre-formatted as a quotation.

When you need to search any generic text for a particular sub-string, use the %SETPATTREGEXP="regexp" and %REGEXPMATCH="string" macro combination. regexp defines the search pattern for all subsequent occurrences of the %REGEXPMATCH macro until the next instance of %SETPATTREGEXP. Since the string parameter is within a template, it is possible to use any of the available macros to generate any text you need, e.g. %QUOTES="%SETREGEXP=""regexp""%REGEXPMATCH=""%TEXT""" is equivalent to %REGEXPQUOTES="regexp".

If a match is found, the text that matches a given regular expression is returned. If the regular expression has subpatterns, the first captured substring is returned, i.e for the regular expression Total amount: *(\S+) only the word following Total amount will be returned but not Total amount itself.

%REGEXPBLINDMATCH="string" is like the %REGEXPMATCH="string" macro except that matched string/substrings are not returned, but may be further extracted using %SUBPATT="n" macros where n is the number of a captured substring; %SUBPATT='0' returns the text matching the entire Regular Expression pattern, 1 is the text of the first matching subpattern, 2 - the second matching subpattern,. etc... Thus the %REGEXPBLINDMATCH="string" macro allows you to have more then one subpattern in its results e.g.

%QUOTES="%SETPATTREGEXP=""total_amount +(\S+).*flowers_type +(\S+)""%REGEXPBLINDMATCH=""%TEXT""pay %SUBPATT=""1"" for %SUBPATT=""2"""

The default PCRE options for templates are PCRE_CASELESS+PCRE_MULTILINE+ PCRE_DOTALL. Matching is done by treating a whole message as one string. CF/LF pairs (0D/0A) are replaced with single LF (0A) characters before matching.

See also:

Regular Expressions Syntax (Basic).

Regular Expressions Syntax (Advanced).

Regular Expression macros.

Templates.


Regular Expressions Syntax (Basic)

A regular expression is a set of rules that describes a generalised string. If the characters that make up a particular string conform to the rules of a particular regular expression, the regular expression is said to match that string.

A few concrete examples usually help after an overblown definition like that one. The regular expression b. matches the strings bovine, above, Bobby, and Bob Jones, but not the strings Bell, b, or Bob. That's because the expression insists that the letter b (lowercase) must be in the string and must be followed immediately by another character.

The regular expression b+, on the other hand, requires the lowercase letter b at least once. This expression matches b and Bob in addition to the example matches for b. in the preceding paragraph. The regular expression b* requires zero or more bs, so it matches any string. That seems to be fairly useless, but it makes more sense as part of a larger regular expression. Bob*y, for example, matches all of Boy, Boby, and Bobby but not Boboby.

Assertions Several so-called assertions are used to anchor parts of the pattern to word or string boundaries. The ^ assertion matches the start of a string, so the regular expression ^fool matches fool and foolhardy but not tomfoolery or April fool. The following table lists the assertions.

Regular-Expression Assertions

Assertion	Matches	Example	Matches	Doesn't Match

^	Start of string	^fool	foolish	Tomfoolery

$	End of string	fool$	April fool	Foolish

\b	Word boundary	be\bside	be side	Beside

\B	Nonword boundary	be\Bside	beside	be side

Atoms The . (period) that you saw in b. earlier in this chapter is an example of a regular-expression atom. Atoms are, as the name suggests, the fundamental building blocks of a regular expression. A full list of atoms appears in the following table.

Regular-Expression Atoms

Atom	Matches	Example	Matches	Doesn't Match

Period (.)	Any character except new line	b.b	Bob	bb

List of characters in brackets	Any one of those characters	^[Bb]	Bob, bob	Rbob

Regular expression in parentheses	Anything that regular expression matches	^a(b.b)c$	Abobc	abbc

Quantifiers A quantifier is a modifier for an atom. It can be used to specify that a particular atom must appear at least once, as in b+. The atom quantifiers are listed in the following table.

Regular-Expression Atom Quantifiers

Quantifier	Matches	Example	Matches	Doesn't Match

*	Zero or more instances of the atom	ab*c	ac, abc	abb

+	One or more instances of the atom	ab+c	Abc	ac

?	Zero or one instances of the atom	ab?c	ac, abc	abbc

{n}	n instances of the atom	ab{2}c	Abbc	abbbc

{n,}	At least n instances of the atom	ab{2,}c	abbc, abbbc	abc

{n,m}	At least n, most m instances of the atom	ab{2,3}c	Abbc	abbbbcat

Special Characters Several special characters are denoted by backslashed letters, with \n being especially familiar to C programmers, perhaps. The following table lists the special characters.

Regular-Expression Special Characters

Symbol	Matches 	Example	Matches	Doesn't Match

\d	Any digit 	b\dd	b4d	Bad

\D	Nondigit 	b\Dd	bdd	b4d

\n	New line

\r	Carriage return

\t	Tab

\f	Form feed

\s	White-space character

\S	Non-white-space character

\w	Alphanumeric character 	a\wb	a2b	a^b

\W	Nonalphanumeric character 	a\Wb	aa^b	Aabb

Backslashed Tokens It is essential that regular expressions be capable of using all characters, so that all possible strings that occur in the real word can be matched. With so many characters having special meanings, a mechanism is required that allows you to represent any arbitrary character in a regular expression. This mechanism is a backslash (\), followed by a numeric quantity. This quantity can take any of the following formats:

Single or double digit	matched quantities after a match. These matched quantities are called backreferences and are explained in a separate section.

Two-or three-digit octal number	the character with that number as character code, unless it's possible to interpret it as a backreference.

x, followed by two hexadecimal digits	the character with that number as its character code. \x3e, for example, is >

c, followed by a single character	the control character. \cG, for example, matches <Ctrl+G>.

Any other character	the character itself. \&, for example, matches the & character

See also:

Regular Expressions Syntax (Advanced)


Regular Expressions Syntax (Advanced)

The Bat! uses Perl-compatible regular expressions.(PCRE) library. The library is a set of functions that implement regular expression pattern matching using the same syntax and semantics as Perl 5, with just a few differences. The current implementation corresponds to Perl 5.005. The syntax and semantics of the regular expressions supported by the PCRE are described in this chapter. For Perl 5 regular expression syntax, read the Perl regular expressions man page at http://www.perl.com/CPAN-local/doc/manual/html/pod/perlre.html

 - Meta-Characters.

 - Backslash.

 - Circumflex and Dollar.

 - Full Stop (Period, Dot).

 - Square Brackets.

 - Vertical Bar.

 - Internal Option Setting.

 - Subpatterns.

 - Repetition.

 - Back References.

 - Assertions.

 - Once-Only Subpatterns.

 - Conditional Subpatterns.

 - Comments.

 - Performance.

 - Limitiations.

 - Differences From Perl.

The PCRE Library, which is open source software, and these chapters (Regular Expressions Syntax (Advanced)) are written by Philip Hazel <ph10@cam.ac.uk>, University of Cambridge Computing Service, Cambridge, England. Phone: +44 1223 334714. Copyright © 1997-1999 University of Cambridge

Regular expressions are also described in the Perl documentation and in a number of other books, some of which have copious examples. Jeffrey Friedl's "Mastering Regular Expressions", published by O'Reilly (ISBN 1-56592-257-3), covers them in great detail. The description here is intended as reference documentation.


Meta-Characters

A regular expression is a pattern that is matched against a subject string from left to right. Most characters stand for themselves in a pattern, and match the corresponding characters in the subject. As a trivial example, the pattern

  The quick brown fox

matches a portion of a subject string that is identical to itself. The power of regular expressions comes from the ability to include alternatives and repetitions in the pattern. These are encoded in the pattern by the use of meta-characters, which do not stand for themselves but instead are interpreted in some special way.

There are two different sets of meta-characters: those that are recognised anywhere in the pattern except within square brackets, and those that are recognised in square brackets. Outside square brackets, the meta-characters are as follows:

\	general escape character with several uses

^	assert start of subject (or line, in multiline mode)

$	assert end of subject (or line, in multiline mode)

.	match any character except newline (by default)

[	start character class definition

|	start of alternative branch

(	start subpattern

)	end subpattern

?	extends the meaning of ( also 0 or 1 quantifier also quantifier minimizer

*	0 or more quantifier

+	1 or more quantifier

{	start min/max quantifier

Part of a pattern that is in square brackets is called a "character class". In a character class the only meta-characters are:

\	general escape character

^	negate the class, but only if the first character

-	indicates character range

]	terminates the character class

The following sections describe the use of each of the meta-characters.

Note: This topic was taken from the PCRE library manual. The PCRE library is open source software, written by Philip Hazel <ph10@cam.ac.uk>, and copyright by the University of Cambridge, England.


Backslash

The backslash character has several uses. Firstly, if it is followed by a non-alphameric character, it takes away any special meaning that character may have. This use of backslash as an escape character applies both inside and outside character classes.

For example, if you want to match a "*" character, you write "\*" in the pattern. This applies whether or not the following character would otherwise be interpreted as a meta-character, so it is always safe to precede a non-alphameric with "\" to specify that it stands for itself. In particular, if you want to match a backslash, you write "\\".

If a pattern is compiled with the PCRE_EXTENDED option, whitespace in the pattern (other than in a character class) and characters between a "#" outside a character class and the next newline character are ignored. An escaping backslash can be used to include a whitespace or "#" character as part of the pattern.

A second use of backslash provides a way of encoding non-printing characters in patterns in a visible manner. There is no restriction on the appearance of non-printing characters, apart from the binary zero that terminates a pattern, but when a pattern is being prepared by text editing, it is usually easier to use one of the following escape sequences than the binary character it represents:

\a	alarm, that is, the BEL character (hex 07)

\cx	"control-x", where x is any character

\e	escape (hex 1B)

\f	formfeed (hex 0C)

\n	newline (hex 0A)

\r	carriage return (hex 0D)

\t	tab (hex 09)

\xhh	character with hex code hh

\ddd	character with octal code ddd, or backreference

The precise effect of "\cx" is as follows: if "x" is a lower case letter, it is converted to upper case. Then bit 6 of the character (hex 40) is inverted. Thus "\cz" becomes hex 1A, but "\c{" becomes hex 3B, while "\c;" becomes hex 7B.

After "\x", up to two hexadecimal digits are read (letters can be in upper or lower case).

After "\0" up to two further octal digits are read. In both cases, if there are fewer than two digits, just those that are present are used. Thus the sequence "\0\x\07" specifies two binary zeros followed by a BEL character. Make sure you supply two digits after the initial zero if the character that follows is itself an octal digit.

The handling of a backslash followed by a digit other than 0 is complicated. Outside a character class, PCRE reads it and any following digits as a decimal number. If the number is less than 10, or if there have been at least that many previous capturing left parentheses in the expression, the entire sequence is taken as a back reference. A description of how this works is given later, following the discussion of parenthesized subpatterns.

Inside a character class, or if the decimal number is greater than 9 and there have not been that many capturing subpatterns, PCRE re-reads up to three octal digits following the backslash, and generates a single byte from the least significant 8 bits of the value. Any subsequent digits stand for themselves. For example:

\040	is another way of writing a space

\40	is the same, provided there are fewer than 40 previous capturing subpatterns

\7	is always a back reference

\11	might be a back reference, or another way of writing a tab

\011	is always a tab

\0113	is a tab followed by the character "3"

\113	is the character with octal code 113 (since there can be no more than 99 back references)

\377	is a byte consisting entirely of 1 bits

\81	is either a back reference, or a binary zero followed by the two characters "8" and "1"

Note that octal values of 100 or greater must not be introduced by a leading zero, because no more than three octal digits are ever read.

All the sequences that define a single byte value can be used both inside and outside character classes. In addition, inside a character class, the sequence "\b" is interpreted as the backspace character (hex 08). Outside a character class it has a different meaning (see below).

The third use of backslash is for specifying generic character types:

\d	any decimal digit

\D	any character that is not a decimal digit

\s	any whitespace character

\S	any character that is not a whitespace character

\w	any "word" character

\W	any "non-word" character

Each pair of escape sequences partitions the complete set of characters into two disjoint sets. Any given character matches one, and only one, of each pair.

A "word" character is any letter or digit or the underscore character, that is, any character which can be part of a Perl "word". The definition of letters and digits is controlled by PCRE's character tables, and may vary if locale- specific matching is taking place (see "Locale support" above). For example, in the "fr" (French) locale, some character codes greater than 128 are used for accented letters, and these are matched by \w.

These character type sequences can appear both inside and outside character classes. They each match one character of the appropriate type. If the current matching point is at the end of the subject string, all of them fail, since there is no character to match.

The fourth use of backslash is for certain simple assertions. An assertion specifies a condition that has to be met at a particular point in a match, without consuming any characters from the subject string. The use of subpatterns for more complicated assertions is described below. The backslashed assertions are

\b	word boundary

\B	not a word boundary

\A	start of subject (independent of multiline mode)

\Z	end of subject or newline at end (independent of multiline mode)

\z	end of subject (independent of multiline mode)

These assertions may not appear in character classes (but note that "\b" has a different meaning, namely the backspace character, inside a character class).

A word boundary is a position in the subject string where the current character and the previous character do not both match \w or \W (i.e. one matches \w and the other matches \W), or the start or end of the string if the first or last character matches \w, respectively.

The \A, \Z, and \z assertions differ from the traditional circumflex and dollar (described below) in that they only ever match at the very start and end of the subject string, whatever options are set. They are not affected by the PCRE_NOTBOL or PCRE_NOTEOL options. The difference between \Z and \z is that \Z matches before a newline that is the last character of the string as well as at the end of the string, whereas \z matches only at the end.

Note: This topic was taken from the PCRE library manual. The PCRE library is open source software, written by Philip Hazel <ph10@cam.ac.uk>, and copyright by the University of Cambridge, England.


Circumflex and Dollar

Outside a character class, in the default matching mode, the circumflex character is an assertion which is true only if the current matching point is at the start of the subject string. Inside a character class, circumflex has an entirely different meaning (see below).

Circumflex need not be the first character of the pattern if a number of alternatives are involved, but it should be the first thing in each alternative in which it appears if the pattern is ever to match that branch. If all possible alternatives start with a circumflex, that is, if the pattern is constrained to match only at the start of the subject, it is said to be an "anchored" pattern. (There are also other constructs that can cause a pattern to be anchored.)

A dollar character is an assertion which is true only if the current matching point is at the end of the subject string, or immediately before a newline character that is the last character in the string (by default). Dollar need not be the last character of the pattern if a number of alternatives are involved, but it should be the last item in any branch in which it appears. Dollar has no special meaning in a character class.

The meaning of dollar can be changed so that it matches only at the very end of the string, by setting the PCRE_DOLLAR_ENDONLY option at compile or matching time. This does not affect the \Z assertion.

The meanings of the circumflex and dollar characters are changed if the PCRE_MULTILINE option is set. When this is the case, they match immediately after and immediately before an internal "\n" character, respectively, in addition to matching at the start and end of the subject string. For example, the pattern /^abc$/ matches the subject string "def

abc" in multiline mode, but not otherwise. Consequently, patterns that are anchored in single line mode because all branches start with "^" are not anchored in multiline mode. The PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE is set.

Note that the sequences \A, \Z, and \z can be used to match the start and end of the subject in both modes, and if all branches of a pattern start with \A is it always anchored, whether PCRE_MULTILINE is set or not.

Note: This topic was taken from the PCRE library manual. The PCRE library is open source software, written by Philip Hazel <ph10@cam.ac.uk>, and copyright by the University of Cambridge, England.


Full Stop (Period, Dot)

Outside a character class, a dot in the pattern matches any one character in the subject, including a non-printing character, but not (by default) newline. If the PCRE_DOTALL option is set, then dots match newlines as well. The handling of dot is entirely independent of the handling of circumflex and dollar, the only relationship being that they both involve newline characters. Dot has no special meaning in a character class.

Note: This topic was taken from the PCRE library manual. The PCRE library is open source software, written by Philip Hazel <ph10@cam.ac.uk>, and copyright by the University of Cambridge, England.


Square Brackets

An opening square bracket introduces a character class, terminated by a closing square bracket. A closing square bracket on its own is not special. If a closing square bracket is required as a member of the class, it should be the first data character in the class (after an initial circumflex, if present) or escaped with a backslash.

A character class matches a single character in the subject; the character must be in the set of characters defined by the class, unless the first character in the class is a circumflex, in which case the subject character must not be in the set defined by the class. If a circumflex is actually required as a member of the class, ensure it is not the first character, or escape it with a backslash.

For example, the character class [aeiou] matches any lower case vowel, while [^aeiou] matches any character that is not a lower case vowel. Note that a circumflex is just a convenient notation for specifying the characters which are in the class by enumerating those that are not. It is not an assertion: it still consumes a character from the subject string, and fails if the current pointer is at the end of the string.

When caseless matching is set, any letters in a class represent both their upper case and lower case versions, so for example, a caseless [aeiou] matches "A" as well as "a", and a caseless [^aeiou] does not match "A", whereas a caseful version would.

The newline character is never treated in any special way in character classes, whatever the setting of the PCRE_DOTALL or PCRE_MULTILINE options is. A class such as [^a] will always match a newline.

The minus (hyphen) character can be used to specify a range of characters in a character class. For example, [d-m] matches any letter between d and m, inclusive. If a minus character is required in a class, it must be escaped with a backslash or appear in a position where it cannot be interpreted as indicating a range, typically as the first or last character in the class.

It is not possible to have the literal character "]" as the end character of a range. A pattern such as [W-]46] is interpreted as a class of two characters ("W" and "-") followed by a literal string "46]", so it would match "W46]" or "-46]". However, if the "]" is escaped with a backslash it is interpreted as the end of range, so [W-\]46] is interpreted as a single class containing a range followed by two separate characters. The octal or hexadecimal representation of "]" can also be used to end a range.

Ranges operate in ASCII collating sequence. They can also be used for characters specified numerically, for example [\000-\037]. If a range that includes letters is used when caseless matching is set, it matches the letters in either case. For example, [W-c] is equivalent to [][\^_`wxyzabc], matched caselessly, and if character tables for the "fr" locale are in use, [\xc8-\xcb] matches accented E characters in both cases.

The character types \d, \D, \s, \S, \w, and \W may also appear in a character class, and add the characters that they match to the class. For example, [\dABCDEF] matches any hexadecimal digit. A circumflex can conveniently be used with the upper case character types to specify a more restricted set of characters than the matching lower case type. For example, the class [^\W_] matches any letter or digit, but not underscore.

All non-alphameric characters other than \, -, ^ (at the start) and the terminating ] are non-special in character classes, but it does no harm if they are escaped.

Note: This topic was taken from the PCRE library manual. The PCRE library is open source software, written by Philip Hazel <ph10@cam.ac.uk>, and copyright by the University of Cambridge, England.


Vertical Bar

Vertical bar characters are used to separate alternative patterns. For example, the pattern

  gilbert|sullivan

matches either "gilbert" or "sullivan". Any number of alternatives may appear, and an empty alternative is permitted (matching the empty string). The matching process tries each alternative in turn, from left to right, and the first one that succeeds is used. If the alternatives are within a subpattern (defined below), "succeeds" means matching the rest of the main pattern as well as the alternative in the subpattern.

Note: This topic was taken from the PCRE library manual. The PCRE library is open source software, written by Philip Hazel <ph10@cam.ac.uk>, and copyright by the University of Cambridge, England.


Internal Option Setting

The settings of PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, and PCRE_EXTENDED can be changed from within the pattern by a sequence of Perl option letters enclosed between "(?" and ")". The option letters are

i	PCRE_CASELESS	Letters in the pattern match both upper and lower case letters. It is equivalent to Perl's /i option.

m	PCRE_MULTILINE	By default, PCRE treats the subject string as consisting of a single "line" of characters (even if it actually contains several newlines). The "start of line" metacharacter (^) matches only at the start of the string, while the "end of line" metacharacter ($) matches only at the end of the string, or before a terminating newline (unless PCRE_DOLLAR_ENDONLY is set). This is the same as Perl.  When PCRE_MULTILINE it is set, the "start of line" and "end of line" constructs match immediately following or immediately before any newline in the subject string, respectively, as well as at the very start and end. This is equivalent to Perl's /m option. If there are no "\n" characters in a subject string, or no occurrences of ^ or $ in a pattern, setting PCRE_MULTILINE has no effect.

s	PCRE_DOTALL	If this bit is set, a dot metacharater in the pattern matches all characters, including newlines. Without it, newlines are excluded. This option is equivalent to Perl's /s option. A negative class such as [^a] always matches a newline character, independent of the setting of this option.

x	PCRE_EXTENDED	If this bit is set, whitespace data characters in the pattern are totally ignored except when escaped or inside a character class, and characters between an unescaped # outside a character class and the next newline character, inclusive, are also ignored. This is equivalent to Perl's /x option, and makes it possible to include comments inside complicated patterns. Note, however, that this applies only to data characters. Whitespace characters may never appear within special character sequences in a pattern, for example within the sequence (?( which introduces a conditional subpattern.

For example, (?im) sets caseless, multiline matching. It is also possible to unset these options by preceding the letter with a hyphen, and a combined setting and unsetting such as (?im-sx), which sets PCRE_CASELESS and PCRE_MULTILINE while unsetting PCRE_DOTALL and PCRE_EXTENDED, is also permitted. If a letter appears both before and after the hyphen, the option is unset.

The scope of these option changes depends on where in the pattern the setting occurs. For settings that are outside any subpattern (defined below), the effect is the same as if the options were set or unset at the start of matching. The following patterns all behave in exactly the same way:

  (?i)abc

  a(?i)bc

  ab(?i)c

  abc(?i)

which in turn is the same as compiling the pattern abc with PCRE_CASELESS set. In other words, such "top level" settings apply to the whole pattern (unless there are other changes inside subpatterns). If there is more than one setting of the same option at top level, the rightmost setting is used.

If an option change occurs inside a subpattern, the effect is different. This is a change of behaviour in Perl 5.005. An option change inside a subpattern affects only that part of the subpattern that follows it, so

  (a(?i)b)c

matches abc and aBc and no other strings (assuming PCRE_CASELESS is not used). By this means, options can be made to have different settings in different parts of the pattern. Any changes made in one alternative do carry on into subsequent branches within the same subpattern. For example,

  (a(?i)b|c)

matches "ab", "aB", "c", and "C", even though when matching "C" the first branch is abandoned before the option setting. This is because the effects of option settings happen at compile time. There would be some very weird behaviour otherwise.

The PCRE-specific options PCRE_UNGREEDY and PCRE_EXTRA can be changed in the same way as the Perl-compatible options by using the characters U and X respectively. The (?X) flag setting is special in that it must always occur earlier in the pattern than any of the additional features it turns on, even when it is at top level. It is best put at the start.

Note: This topic was taken from the PCRE library manual. The PCRE library is open source software, written by Philip Hazel <ph10@cam.ac.uk>, and copyright by the University of Cambridge, England.


Subpatterns

Subpatterns are delimited by parentheses (round brackets), which can be nested.

Marking part of a pattern as a subpattern does two things:

1. It localizes a set of alternatives. For example, the pattern

  cat(aract|erpillar|)

matches one of the words "cat", "cataract", or "caterpillar". Without the parentheses, it would match "cataract", "erpillar" or the empty string.

2. It sets up the subpattern as a capturing subpattern (as defined above). Opening parentheses are counted from left to right (starting from 1) to obtain the numbers of the capturing subpatterns.

For example, if the string "the red king" is matched against the pattern

  the ((red|white) (king|queen))

the captured substrings are "red king", "red", and "king", and are numbered 1, 2, and 3.

The fact that plain parentheses fulfil two functions is not always helpful. There are often times when a grouping subpattern is required without a capturing requirement. If an opening parenthesis is followed by "?:", the subpattern does not do any capturing, and is not counted when computing the number of any subsequent capturing subpatterns. For example, if the string "the white queen" is matched against the pattern

  the ((?:red|white) (king|queen))

the captured substrings are "white queen" and "queen", and are numbered 1 and 2. The maximum number of captured substrings is 99, and the maximum number of all subpatterns, both capturing and non-capturing, is 200.

As a convenient shorthand, if any option settings are required at the start of a non-capturing subpattern, the option letters may appear between the "?" and the ":". Thus the two patterns

  (?i:saturday|sunday)

  (?:(?i)saturday|sunday)

match exactly the same set of strings. Because alternative branches are tried from left to right, and options are not reset until the end of the subpattern is reached, an option setting in one branch does affect subsequent branches, so the above patterns match "SUNDAY" as well as "Saturday".

Note: This topic was taken from the PCRE library manual. The PCRE library is open source software, written by Philip Hazel <ph10@cam.ac.uk>, and copyright by the University of Cambridge, England.


Repetition

Repetition is specified by quantifiers, which can follow any of the following items:

  a single character, possibly escaped

  the . metacharacter

  a character class

  a back reference (see next section)

  a parenthesized subpattern (unless it is an assertion - see below)

The general repetition quantifier specifies a minimum and maximum number of permitted matches, by giving the two numbers in curly brackets (braces), separated by a comma. The numbers must be less than 65536, and the first must be less than or equal to the second. For example:

  z{2,4}

matches "zz", "zzz", or "zzzz". A closing brace on its own is not a special character. If the second number is omitted, but the comma is present, there is no upper limit; if the second number and the comma are both omitted, the quantifier specifies an exact number of required matches. Thus

  [aeiou]{3,}

matches at least 3 successive vowels, but may match many more, while

  \d{8}

matches exactly 8 digits. An opening curly bracket that appears in a position where a quantifier is not allowed, or one that does not match the syntax of a quantifier, is taken as a literal character. For example, {,6} is not a quantifier, but a literal string of four characters.

The quantifier {0} is permitted, causing the expression to behave as if the previous item and the quantifier were not present.

For convenience (and historical compatibility) the three most common quantifiers have single-character abbreviations:

*	is equivalent to {0,}

+	is equivalent to {1,}

?	is equivalent to {0,1}

It is possible to construct infinite loops by following a subpattern that can match no characters with a quantifier that has no upper limit, for example:

  (a?)*

Earlier versions of Perl and PCRE used to give an error at compile time for such patterns. However, because there are cases where this can be useful, such patterns are now accepted, but if any repetition of the subpattern does in fact match no characters, the loop is forcibly broken.

By default, the quantifiers are "greedy", that is, they match as much as possible (up to the maximum number of permitted times), without causing the rest of the pattern to fail. The classic example of where this gives problems is in trying to match comments in C programs. These appear between the sequences /* and */ and within the sequence, individual * and / characters may appear. An attempt to match C comments by applying the pattern

  /\*.*\*/

to the string

  /* first command */  not comment  /* second comment */

fails, because it matches the entire string due to the greediness of the .* item.

However, if a quantifier is followed by a question mark, then it ceases to be greedy, and instead matches the minimum number of times possible, so the pattern

  /\*.*?\*/

does the right thing with the C comments. The meaning of the various quantifiers is not otherwise changed, just the preferred number of matches. Do not confuse this use of question mark with its use as a quantifier in its own right. Because it has two uses, it can sometimes appear doubled, as in

  \d??\d

which matches one digit by preference, but can match two if that is the only way the rest of the pattern matches.

If the PCRE_UNGREEDY option is set (an option which is not available in Perl) then the quantifiers are not greedy by default, but individual ones can be made greedy by following them with a question mark. In other words, it inverts the default behaviour.

When a parenthesized subpattern is quantified with a minimum repeat count that is greater than 1 or with a limited maximum, more store is required for the compiled pattern, in proportion to the size of the minimum or maximum.

If a pattern starts with .* or .{0,} and the PCRE_DOTALL option (equivalent to Perl's /s) is set, thus allowing the . to match newlines, then the pattern is implicitly anchored, because whatever follows will be tried against every character position in the subject string, so there is no point in retrying the overall match at any position after the first. PCRE treats such a pattern as though it were preceded by \A. In cases where it is known that the subject string contains no newlines, it is worth setting PCRE_DOTALL when the pattern begins with .* in order to obtain this optimization, or alternatively using ^ to indicate anchoring explicitly.

When a capturing subpattern is repeated, the value captured is the substring that matched the final iteration. For example, after

  (tweedle[dume]{3}\s*)+

has matched "tweedledum tweedledee" the value of the captured substring is "tweedledee". However, if there are nested capturing subpatterns, the corresponding captured values may have been set in previous iterations. For example, after

  /(a|(b))+/

matches "aba" the value of the second captured substring is "b".

Note: This topic was taken from the PCRE library manual. The PCRE library is open source software, written by Philip Hazel <ph10@cam.ac.uk>, and copyright by the University of Cambridge, England.


Back References

Outside a character class, a backslash followed by a digit greater than 0 (and possibly further digits) is a back reference to a capturing subpattern earlier (i.e. to its left) in the pattern, provided there have been that many previous capturing left parentheses.

However, if the decimal number following the backslash is less than 10, it is always taken as a back reference, and causes an error only if there are not that many capturing left parentheses in the entire pattern. In other words, the parentheses that are referenced need not be to the left of the reference for numbers less than 10. See the section entitled "Backslash" above for further details of the handling of digits following a backslash.

A back reference matches whatever actually matched the capturing subpattern in the current subject string, rather than anything matching the subpattern itself. So the pattern

  (sens|respons)e and \1ibility

matches "sense and sensibility" and "response and responsibility", but not "sense and responsibility". If caseful matching is in force at the time of the back reference, then the case of letters is relevant. For example,

  ((?i)rah)\s+\1

matches "rah rah" and "RAH RAH", but not "RAH rah", even though the original capturing subpattern is matched caselessly.

There may be more than one back reference to the same subpattern. If a subpattern has not actually been used in a particular match, then any back references to it always fail. For example, the pattern

  (a|(bc))\2

always fails if it starts to match "a" rather than "bc". Because there may be up to 99 back references, all digits following the backslash are taken as part of a potential back reference number. If the pattern continues with a digit character, then some delimiter must be used to terminate the back reference. If the PCRE_EXTENDED option is set, this can be whitespace. Otherwise an empty comment can be used.

A back reference that occurs inside the parentheses to which it refers fails when the subpattern is first used, so, for example, (a\1) never matches. However, such references can be useful inside repeated subpatterns. For example, the pattern

  (a|b\1)+

matches any number of "a"s and also "aba", "ababaa" etc. At each iteration of the subpattern, the back reference matches the character string corresponding to the previous iteration. In order for this to work, the pattern must be such that the first iteration does not need to match the back reference. This can be done using alternation, as in the example above, or by a quantifier with a minimum of zero.

Note: This topic was taken from the PCRE library manual. The PCRE library is open source software, written by Philip Hazel <ph10@cam.ac.uk>, and copyright by the University of Cambridge, England.


Assertions

An assertion is a test on the characters following or preceding the current matching point that does not actually consume any characters. The simple assertions coded as \b, \B, \A, \Z, \z, ^ and $ are described above. More complicated assertions are coded as subpatterns. There are two kinds: those that look ahead of the current position in the subject string, and those that look behind it.

An assertion subpattern is matched in the normal way, except that it does not cause the current matching position to be changed. Lookahead assertions start with (?= for positive assertions and (?! for negative assertions. For example,

  \w+(?=;)

matches a word followed by a semicolon, but does not include the semicolon in the match, and

  foo(?!bar)

matches any occurrence of "foo" that is not followed by "bar". Note that the apparently similar pattern

  (?!foo)bar

does not find an occurrence of "bar" that is preceded by something other than "foo"; it finds any occurrence of "bar" whatsoever, because the assertion (?!foo) is always true when the next three characters are "bar". A lookbehind assertion is needed to achieve this effect.

Lookbehind assertions start with (?<= for positive assertions and (?<! for negative assertions. For example,

  (?<!foo)bar

does find an occurrence of "bar" that is not preceded by "foo". The contents of a lookbehind assertion are restricted such that all the strings it matches must have a fixed length. However, if there are several alternatives, they do not all have to have the same fixed length. Thus

  (?<=bullock|donkey)

is permitted, but

  (?<!dogs?|cats?)

causes an error at compile time. Branches that match different length strings are permitted only at the top level of a lookbehind assertion. This is an extension compared with Perl 5.005, which requires all branches to match the same length of string. An assertion such as

  (?<=ab(c|de))

is not permitted, because its single top-level branch can match two different lengths, but it is acceptable if rewritten to use two top-level branches:

  (?<=abc|abde)

The implementation of lookbehind assertions is, for each alternative, to temporarily move the current position back by the fixed width and then try to match. If there are insufficient characters before the current position, the match is deemed to fail. Lookbehinds in conjunction with once-only subpatterns can be particularly useful for matching at the ends of strings; an example is given at the end of the section on once-only subpatterns.

Several assertions (of any sort) may occur in succession. For example,

  (?<=\d{3})(?<!999)foo

matches "foo" preceded by three digits that are not "999". Furthermore, assertions can be nested in any combination. For example,

  (?<=(?<!foo)bar)baz

matches an occurrence of "baz" that is preceded by "bar" which in turn is not preceded by "foo".

Assertion subpatterns are not capturing subpatterns, and may not be repeated, because it makes no sense to assert the same thing several times. If an assertion contains capturing subpatterns within it, these are always counted for the purposes of numbering the capturing subpatterns in the whole pattern. Substring capturing is carried out for positive assertions, but it does not make sense for negative assertions.

Assertions count towards the maximum of 200 parenthesized subpatterns.

Note: This topic was taken from the PCRE library manual. The PCRE library is open source software, written by Philip Hazel <ph10@cam.ac.uk>, and copyright by the University of Cambridge, England.


Once-Only Subpatterns

With both maximizing and minimizing repetition, failure of what follows normally causes the repeated item to be re-evaluated to see if a different number of repeats allows the rest of the pattern to match. Sometimes it is useful to prevent this, either to change the nature of the match, or to cause it fail earlier than it otherwise might, when the author of the pattern knows there is no point in carrying on.

Consider, for example, the pattern \d+foo when applied to the subject line

  123456bar

After matching all 6 digits and then failing to match "foo", the normal action of the matcher is to try again with only 5 digits matching the \d+ item, and then with 4, and so on, before ultimately failing. Once-only subpatterns provide the means for specifying that once a portion of the pattern has matched, it is not to be re-evaluated in this way, so the matcher would give up immediately on failing to match "foo" the first time. The notation is another kind of special parenthesis, starting with (?> as in this example:

  (?>\d+)bar

This kind of parenthesis "locks up" the  part of the pattern it contains once it has matched, and a failure further into the pattern is prevented from backtracking into it. Backtracking past it to previous items, however, works as normal.

An alternative description is that a subpattern of this type matches the string of characters that an identical standalone pattern would match, if anchored at the current point in the subject string.

Once-only subpatterns are not capturing subpatterns. Simple cases such as the above example can be thought of as a maximizing repeat that must swallow everything it can. So, while both \d+ and \d+? are prepared to adjust the number of digits they match in order to make the rest of the pattern match, (?>\d+) can only match an entire sequence of digits.

This construction can of course contain arbitrarily complicated subpatterns, and it can be nested.

Once-only subpatterns can be used in conjunction with lookbehind assertions to specify efficient matching at the end of the subject string. Consider a simple pattern such as

  abcd$

when applied to a long string which does not match it. Because matching proceeds from left to right, PCRE will look for each "a" in the subject and then see if what follows matches the rest of the pattern. If the pattern is specified as

  ^.*abcd$

then the initial .* matches the entire string at first, but when this fails, it backtracks to match all but the last character, then all but the last two characters, and so on. Once again the search for "a" covers the entire string, from right to left, so we are no better off. However, if the pattern is written as

  ^(?>.*)(?<=abcd)

then there can be no backtracking for the .* item; it can match only the entire string. The subsequent lookbehind assertion does a single test on the last four characters. If it fails, the match fails immediately. For long strings, this approach makes a significant difference to the processing time.

Note: This topic was taken from the PCRE library manual. The PCRE library is open source software, written by Philip Hazel <ph10@cam.ac.uk>, and copyright by the University of Cambridge, England.


Conditional Subpatterns

It is possible to cause the matching process to obey a subpattern conditionally or to choose between two alternative subpatterns, depending on the result of an assertion, or whether a previous capturing subpattern matched or not. The two possible forms of conditional subpattern are

  (?(condition)yes-pattern)

  (?(condition)yes-pattern|no-pattern)

If the condition is satisfied, the yes-pattern is used; otherwise the no-pattern (if present) is used. If there are more than two alternatives in the subpattern, a compile-time error occurs.

There are two kinds of condition. If the text between the parentheses consists of a sequence of digits, then the condition is satisfied if the capturing subpattern of that number has previously matched. Consider the following pattern, which contains non-significant white space to make it more readable (assume the PCRE_EXTENDED option) and to divide it into three parts for ease of discussion:

  ( \( )?    [^()]+    (?(1) \) )

The first part matches an optional opening parenthesis, and if that character is present, sets it as the first captured substring. The second part matches one or more characters that are not parentheses. The third part is a conditional subpattern that tests whether the first set of parentheses matched or not. If they did, that is, if subject started with an opening parenthesis, the condition is true, and so the yes-pattern is executed and a closing parenthesis is required. Otherwise, since no-pattern is not present, the subpattern matches nothing. In other words, this pattern matches a sequence of non-parentheses, optionally enclosed in parentheses.

If the condition is not a sequence of digits, it must be an assertion. This may be a positive or negative lookahead or lookbehind assertion. Consider this pattern, again containing non-significant white space, and with the two alternatives on the second line:

  (?(?=[^a-z]*[a-z])

  \d{2}[a-z]{3}-\d{2}  |  \d{2}-\d{2}-\d{2} )

The condition is a positive lookahead assertion that matches an optional sequence of non-letters followed by a letter. In other words, it tests for the presence of at least one letter in the subject. If a letter is found, the subject is matched against the first alternative; otherwise it is matched against the second. This pattern matches strings in one of the two forms dd-aaa-dd or dd-dd-dd, where aaa are letters and dd are digits.

Note: This topic was taken from the PCRE library manual. The PCRE library is open source software, written by Philip Hazel <ph10@cam.ac.uk>, and copyright by the University of Cambridge, England.


Comments

The sequence (?# marks the start of a comment which continues up to the next closing parenthesis. Nested parentheses are not permitted. The characters that make up a comment play no part in the pattern matching at all.

If the PCRE_EXTENDED option is set, an unescaped # character outside a character class introduces a comment that continues up to the next newline character in the pattern.

Note: This topic was taken from the PCRE library manual. The PCRE library is open source software, written by Philip Hazel <ph10@cam.ac.uk>, and copyright by the University of Cambridge, England.


Performance

Certain items that may appear in patterns are more efficient than others. It is more efficient to use a character class like [aeiou] than a set of alternatives such as (a|e|i|o|u). In general, the simplest construction that provides the required behaviour is usually the most efficient. Jeffrey Friedl's book contains a lot of discussion about optimizing regular expressions for efficient performance.

When a pattern begins with .* and the PCRE_DOTALL option is set, the pattern is implicitly anchored by PCRE, since it can match only at the start of a subject string. However, if PCRE_DOTALL is not set, PCRE cannot make this optimization, because the . metacharacter does not then match a newline, and if the subject string contains newlines, the pattern may match from the character immediately following one of them instead of from the very start. For example, the pattern

   (.*) second

matches the subject "first\nand second" (where \n stands for a newline character) with the first captured substring being "and". In order to do this, PCRE has to retry the match starting after every newline in the subject.

If you are using such a pattern with subject strings that do not contain newlines, the best performance is obtained by setting PCRE_DOTALL, or starting the pattern with ^.* to indicate explicit anchoring. That saves PCRE from having to scan along the subject looking for a newline to restart at.

Note: This topic was taken from the PCRE library manual. The PCRE library is open source software, written by Philip Hazel <ph10@cam.ac.uk>, and copyright by the University of Cambridge, England.


Limitiations

There are some size limitations in PCRE but it is hoped that they will never in practice be relevant. The maximum length of a compiled pattern is 65539 (sic) bytes. All values in repeating quantifiers must be less than 65536. The maximum number of capturing subpatterns is 99. The maximum number of all parenthesized subpatterns, including capturing subpatterns, assertions, and other types of subpattern, is 200.

The maximum length of a subject string is the largest positive number that an integer variable can hold. However, PCRE uses recursion to handle subpatterns and indefinite repetition. This means that the available stack space may limit the size of a subject string that can be processed by certain patterns.

Note: This topic was taken from the PCRE library manual. The PCRE library is open source software, written by Philip Hazel <ph10@cam.ac.uk>, and copyright by the University of Cambridge, England.


Differences From Perl

The differences described here are with respect to Perl 5.005.

1. By default, a whitespace character is any character that the C library function isspace recognizes, though it is possible to compile PCRE with alternative character type tables. Normally isspace matches space, formfeed, newline, carriage return, horizontal tab, and vertical tab. Perl 5 no longer includes vertical tab in its set of whitespace characters. The \v escape that was in the Perl documentation for a long time was never in fact recognized. However, the character itself was treated as whitespace at least up to 5.002. In 5.004 and 5.005 it does not match \s.

2. PCRE does not allow repeat quantifiers on lookahead assertions. Perl permits them, but they do not mean what you might think. For example, (?!a){3} does not assert that the next three characters are not "a". It just asserts that the next character is not "a" three times.

3. Capturing subpatterns that occur inside negative lookahead assertions are counted, but their entries in the offsets vector are never set. Perl sets its numerical variables from any such patterns that are matched before the assertion fails to match something (thereby succeeding), but only if the negative lookahead assertion contains just one branch.

4. Though binary zero characters are supported in the subject string, they are not allowed in a pattern string because it is passed as a normal C string, terminated by zero. The escape sequence "\0" can be used in the pattern to represent a binary zero.

5. The following Perl escape sequences are not supported: \l, \u, \L, \U, \E, \Q. In fact these are implemented by Perl's general string-handling and are not part of its pattern matching engine.

6. The Perl \G assertion is not supported as it is not relevant to single pattern matches.

7. Fairly obviously, PCRE does not support the (?{code}) construction.

8. There are at the time of writing some oddities in Perl 5.005_02 concerned with the settings of captured strings when part of a pattern is repeated. For example, matching "aba" against the pattern /^(a(b)?)+$/ sets $2 to the value "b", but matching "aabbaa" against /^(aa(bb)?)+$/ leaves $2 unset. However, if the pattern is changed to /^(aa(b(b))?)+$/ then $2 (and $3) get set.

In Perl 5.004 $2 is set in both cases, and that is also true of PCRE. If in the future Perl changes to a consistent state that is different, PCRE may change to follow.

9. Another as yet unresolved discrepancy is that in Perl 5.005_02 the pattern /^(a)?(?(1)a|b)+$/ matches the string "a", whereas in PCRE it does not. However, in both Perl and PCRE /^(a)?a/ matched against "a" leaves $1 unset.

10. PCRE provides some extensions to the Perl regular expression facilities:

(a) Although lookbehind assertions must match fixed length strings, each alternative branch of a lookbehind assertion can match a different length of string. Perl 5.005 requires them all to have the same length.

(b) If PCRE_DOLLAR_ENDONLY is set and PCRE_MULTILINE is not set, the $ meta-character matches only at the very end of the string.

(c) If PCRE_EXTRA is set, a backslash followed by a letter with no special meaning is faulted.

(d) If PCRE_UNGREEDY is set, the greediness of the repetition quantifiers is inverted, that is, by default they are not greedy, but if followed by a question mark they are.

Note: This topic was taken from the PCRE library manual. The PCRE library is open source software, written by Philip Hazel <ph10@cam.ac.uk>, and copyright by the University of Cambridge, England.


Submission Forms

Submission forms are a tool for creating queries that are automatically processed. A query is actually a message with strictly defined fields and string variables.

The queries come from a user equipped with The Bat! software with form templates (files with a TBC-extension). Such a user is referred to as the client. Before submitting a query, The Bat! asks the user to fill out a form, which looks very much like forms that you have probably filled out on the Web. The program that processes user requests is known as the server. The Bat! transforms data filled in by the user to an e-mail message, then encrypts and signs the message digitally. This message is sent to the server via e-mail. The address of the server is defined in a form template. The system of interacting of client and server by means of queries and replies is called The Bat! Client-Server.

This system is intended for remote access to data and managing data in off-line mode securely. The purpose of this system is to control bank accounts, make ticket and hotel reservations, etc. In order to provide secure transactions, encryption and digital signing is used (RSA/IDEA/MD5 algorithms), as defined by RFC-1991. The Server software is specific and is task dependent: Internet-shops, Banks or Ticket Reservation Agencies may use different types of server software, but the client, using The Bat!, can use all of their services seamlessly.

In order to provide a proper transaction, the format of query fields must be equal on both client and server parts. As the server usually works with more then one client, the form templates (TBC-files) are usually created on the server and then signed and sent to the clients before starting any transactions between the client and the server. While processing transactions, the server can start new kinds of services for its users; in this case, the server would send any new versions of form templates in order for the client to be able to use those new services. Upon reception of a template file and verification of the digital signature, the client adds it to the list of template forms.

The presence of a digital signature is mandatory. It does not only ensure that the formats are equal on both client and server, but protects the system from intrusion of unauthorised templates. This unauthorised intrusion can come as a templates renewal and can cause all or a part of clients to have unauthorised templates instead of authorised ones. This can cause "freezing" of networks or information drain. The changing of a server's e-mail address in a form template can cause such a drain.

See also: The Format of a Submission Form Template.


The Format of a Form Template
The Format of a Submission Form Template

Form templates are stored in a text file with a TBC-extension. The file content is signed with a digital signature. Form templates (TBC-files) are usually created on the server, signed and then sent to clients before starting any transactions. Upon receipt of a template file and verification of the digital signature, the client adds it to the list of template forms (Options/Submission Forms). See introduction to learn more about submission forms.

A template describes the properties of a screen form window (which is filled in by the client), e-mail message attributes (in which the query will be sent) and the requested variables. Each string of a form template can contain one keyword with one or more parameters. Lines that start with ";" character are treated as comments.

Window and Message Properties

The MSG keyword is used to define the properties of a screen form window and message attributes, other keywords are used to fill in the form. MSG keyword can have the following parameters: FORMTITLE (title of the screen form window, string value), FORMWIDTH (width of the window, numeric value), FORMHEIGHT (height of the window, numeric value), AREAWIDTH (width of the area inside a window, this area will be scrollable if it exceeds the window, numeric value), AREAHEIGHT (height of the area inside a window, numeric value), TO (e-mail address of destination server, string value), SUBJ (Subject filed of the message, string value), PRIORITY (priority type of the message, string value), ENCRYPT (whether the message should be encrypted, ON/OFF), SIGN (whether the message should be signed, ON/OFF), BATCH (whether this query is to be followed by more queries as part of a group submission), QUEUEOUT (do not send the message immediately; just queue it in the outbox), TPL (the query content is plain text, human-readable), NFO (info added as plaintext before the encrypted data), FILEDLGTITLE (title for the file open dialog window for a VFILERE command), FILEDEFNAME (used by VFILERE to specify the file name that appears in the file open window when the window opens), FILEFILTER (used by VFILERE to determine which file masks will be available in the file open window), FILEDEFEXT (used by VFILERE, if you want a file extension automatically appended to the filename typed in the file open window).

Query Content

Query content is the data that a user has entered while filling in the on-screen form. When the user clicks the OK button in a form, The Bat! creates an e-mail message with the query content. If stated in the form template, the message content will be signed and/or encrypted. The message will then be sent via e-mail to the server. The e-mail address of the server is also stated in the form template.

If the TPL parameter of a MSG keyword is not specified, the message body appears with an unlimited-length line and contains the form variables, which are separated by an ampersand ("&") character. The names of the variables are defined in the form template. The values of the variables are taken from the fields of the on-screen form, which the user has filled in before clicking OK. In the query string that is transmitted to server in the message body, the name and the value of a variable are separated by an equals sign ("=" character). E.g., if the query contains two variables, named servicetype and accountnumber, the first variable has the value "getaccountlog" and the second variable has the value "849780094"; in which case the message body will look like this:

servicetype=getaccountlog&accountnumber=849780094

This generation method for a query string conforms to RFC1866 (paragraph 8.2.1, application/x-www-form-urlencoded content-type).

The names and values of variables can contain any characters, but some characters should be "escaped" according to the following rules: the space character must be replaced by a plus sign character. Non-alphanumeric characters must be replaced by "%HH", a percent sign and two hexadecimal digits representing the ASCII code of the character. Line breaks, as in multi-line text field values, are represented as CR LF pairs, i.e. "%0D%0A".

If the TPL parameter of a MSG keyword is specified, the query will be sent in human-readable plain text conforming to a given template. You can specify a multiline template where each additional TPL parameter adds a line to the template. Names of variables must be enclosed in $-characters, and will be replaced by the related values of the form data entries.

Overview of Form Elements

A screen form can contain such elements as input lines, lists, check-boxes, labels and buttons. All these elements are defined in a form template by means of keywords: EDIT (single-line input field), MEMO (multi-line input field), CHECKBOX, LISTBOX (standard list), COMBOBOX (drop-down list) - all of these elements define variables, one variable per element. Besides that, there is a special invisible element, HIDDEN - the user cannot affect the value set by this element, and the visible LABEL element, which doesn't define a variable and is used as a label for any other visible element. Two elements are used to control the screen form: SUBMIT (the button that causes the query to be sent to server) and CANCEL (button that cancels and closes the form).

Overview of Element Parameters

Screen form elements have the following parameters: X, Y (coordinates of the topmost left corner within a window), WIDTH, HEIGHT (the width and height of an element, most of the elements use default parameter values or they are calculated from the font height, so these parameters are optional), NAME, VALUE, DEFTPL, VBODYRE (defines the name and value of variable, applies to all elements except LABEL, CHECKLISTBOX, SUBMIT and CANCEL). The EDIT element can have a MASK parameter that pre-defines the format of input and a PASSWORD parameter that causes it to display an asterisk character in place of any entered text; LISTBOX, COMBOBOX and CHECKLISTBOX elements can have an ITEM parameter that adds an item to the list; LABEL, CHECKBOX, SUBMIT and CANCEL elements can have a CAPTION parameter.

The LABEL element also has some other parameters: FOCUSNAME, which links the label to another element - if the value of the CAPTION argument of a label includes an accelerator key (an "&" prefix to the accelerator character) and SHOWACCEL is ON, the element named in the value of the FOCUSNAME parameter gains the focus when the user presses the accelerator key. The LABEL keyword can also have a JUSTIFY parameter, which specifies how text is aligned within the label. The value of JUSTIFY can be one of: LEFT (align text to the left side of the label), CENTER (center text horizontally in the label), RIGHT (align text to the right side of the label), WORDWRAP (allows the label to display multiple lines of text)

List of Form Elements

EDIT	Single-line input field. Use the EDIT element to put a standard Windows edit box control on the screen form. Edit boxes are used to retrieve information, which the client can type into an edit box. The client can be forced to enter only valid characters using a MASK parameter. The MASK can be also used to format the display of data. Mandatory parameters: X, Y, NAME; optional parameters: WIDTH, HEIGHT, VALUE, DEFTPL, VBODYRE, MASK, PASSWORD.

MEMO	Multi-line input field, which displays text to the client and permits the client to enter text into the application much like the EDIT component. The difference is that the MEMO element permits multiple lines to be entered or displayed, but doesn't permit masked input, unlike EDIT. Mandatory parameters: X, Y, NAME; optional parameters: WIDTH, HEIGHT, VALUE, DEFTPL, VBODYRE.

CHECKBOX	Switch. This element is used to present On/Off (Yes/No, True/False) options to the client, particularly where more than one choice is available at a time from a group of choices. The string value of the checkbox can be either "on" or "off". When the form is submitted with a value of "on", it will be sent as "name=on". Mandatory parameters: X, Y, NAME; optional parameters: WIDTH, HEIGHT, VALUE.

LISTBOX	Standard list. This element defines a Windows list box. A list box displays a list from which users can select one item. Mandatory parameters: X, Y, NAME; optional parameters: ITEM, WIDTH, HEIGHT, VALUE, COLUMNS.

COMBOBOX	Drop-down list. This element defines a list that has much in common with LISTBOX, but it drops down to allow one item to be selected. Mandatory parameters: X, Y, NAME; optional parameters: ITEM , WIDTH, HEIGHT, VALUE.

CHECKLISTBOX	Multiple-checkboxes list. This element is similar to a list box, except that each item has a check box next to it. Users can check or uncheck items in the list. Mandatory parameters: X, Y; optional parameters: ITEM , WIDTH, HEIGHT, COLUMNS.

HIDDEN	Hidden element. Allows embedded information within the form, which cannot be changed by the client. The NAME and VALUE parameters of this element will be sent to the server without modifications. Mandatory parameters: NAME, VALUE.

LABEL	Label. It displays text on a window. Usually this text labels some other element. Mandatory parameters: X, Y, CAPTION, optional parameters: WIDTH, HEIGHT, FOCUSNAME, JUSTIFY, SHOWACCEL, WORDWRAP.

SUBMIT	Submit button. When pressed, sends the contents of the form to the server. Mandatory parameters: X, Y, optional parameters: WIDTH, HEIGHT, CAPTION.

CANCEL	Cancel button. When pressed, closes the form and cancels client input. Mandatory parameters: X, Y, optional parameters: WIDTH, HEIGHT, CAPTION.

List of Element Parameters

X	Horizontal coordinate of the left edge of an element within a form. This is a mandatory parameter for all visible elements: EDIT, MEMO, CHECKBOX, LISTBOX, COMBOBOX, LABEL, SUBMIT, CANCEL, e.g. all except HIDDEN. Numeric value.

Y	Vertical coordinate of the top edge of an element within a form. Coordinates run from top to bottom. This is a mandatory parameter for all visible elements: EDIT, MEMO, CHECKBOX, LISTBOX, COMBOBOX, LABEL, SUBMIT, CANCEL, e.g. all except HIDDEN. Numeric value.

WIDTH	Width of an element. The width of all visible elements is set by default. This is an optional parameter for all visible elements: EDIT, MEMO, CHECKBOX, LISTBOX, COMBOBOX, LABEL, SUBMIT, CANCEL, e.g. all except HIDDEN. Numeric value.

HEIGHT	Height of an element. The height of all visible elements is set to a default value determined by the font height. This is an optional parameter for all visible elements: EDIT, MEMO, CHECKBOX, LISTBOX, COMBOBOX, LABEL, SUBMIT, CANCEL, e.g. all except HIDDEN. Numeric value.

NAME	Variable name. This is a mandatory parameter for EDIT, MEMO, CHECKBOX, LISTBOX and COMBOBOX. Numeric value.

VALUE	Default value. This is a mandatory parameter for HIDDEN and optional for EDIT, MEMO and CHECKBOX. String value.

CAPTION	Caption. This is a mandatory parameter for LABEL and CHECKBOX and optional for SUBMIT and CANCEL. String value.

FOCUSNAME	Name of the element to be focused by a label. It defines the element which links the label to another element - if the value of the CAPTION argument of a label includes an accelerator key ("&" character), the element named as the value of this parameter gains the focused when the user presses the accelerator key. This is an optional parameter for LABEL. String value.

JUSTIFY	Justifies label text. This parameter specifies how text is aligned within a label. This is an optional parameter for a LABEL. The value of JUSTIFY can be one of: LEFT (align text to the left side of the label), CENTER (center text horizontally in the label), RIGHT (align text to the right side of the label).

SHOWACCEL	Control the accelerator character. This parameter determines how an ampersand in the caption of a label appears. Boolean value. If value is ON, an ampersand appears as an underline under the character to its right in the caption indicating that the underlined character is an accelerator character. If value is OFF, the ampersand character appears as an ampersand.

ITEM	Defines an item of a list element: LISTBOX, COMBOBOX or CHECKLISTBOX. Use two comma-separated string values for LISTBOX, COMBOBOX and three for CHECKLISTBOX. The first value defines the item name, second - the item caption and the third argument (which applies only to CHECKLISTBOX) defines whether an item is checked (value is empty) or unchecked (value is not empty).

WORDWRAP	Multiple lines. Boolean value. Set WordWrap to ON to allow the label to display multiple line of text. When WordWrap is ON, text that is too wide for the label control wraps at the right margin and continues on additional lines. Set WordWrap to OFF to limit the label to a single line. When WordWrap is OFF, text that is too wide for the label appears truncated.

PASSWORD	Password input. If the value is ON, the EDIT control displays a special character (asterisk) in place of any entered text.

COLUMNS	Number of columns in a list element. This is an optional parameter for LISTBOX and CHECKLISTBOX elements. Numeric value. Use COLUMNS to specify the number of columns that are visible in a multi-column list box without having to use the horizontal scrollbar. Multi-column list boxes have a horizontal scrollbar that allows users to view multiple columns as they wrap. The default value for COLUMNS is 0, meaning that the list box is not multi-column. That is, users can only scroll vertically and the list of items will not wrap. For COLUMNS values greater than 0, multiple columns accommodate the items as they wrap beyond the bottom of the list box. The COLUMNS parameter specifies the number of columns that are visible without having to horizontally scroll the list box. The width of each column depends upon both the WIDTH parameter and the number of columns.

DEFTPL	Default value template. The VALUE parameter of the element will be set using macros. The difference from standard template macros is that the '#' character is used here as a prefix instead of '%'. E.g. DEFTPL="#FOLDERFROMNAME" as an argument of an EDIT element sets the VALUE of the element to the "FROM" name of the current folder's Identity properties. For use in EDIT, MEMO and HIDDEN elements.

VBODYRE	Default value: use a regular expression on message body. Similar to DEFTPL except that the value is not a template with macros but a regular expression. The match is performed on the text of the currently selected message, e.g. VBODYRE="^UserFullName:  (.+)$".

VFILERE	Default value: regular expression on a particular text file. Similar to VBODYRE except that the value is extracted from a text file, not the message body. The user will be given a standard windows file open dialog to select a file.

MASK Parameter: Character-By-Character Validation

Use the MASK parameter to restrict the characters a user can enter into an EDIT element to valid characters and formats. If the user attempts to enter an invalid character, the edit control does not accept the character. Validation is performed on a character-by-character basis. Ensure that the contents of the MASK parameter don't start with an ampersand (&) character when using character-by-character validation. If the contents of a MASK parameter starts with an ampersand character, it is treated as advanced mask.

A mask consists of three fields separated by semicolons. The first part of the mask is the mask itself. The second part is the character that determines whether the literal characters of a mask are saved as part of the data. The third part of the mask is the character used to represent editable character positions in the mask.

This is a list of the special characters that can be used in the first field of the mask:

!	If a '!' character appears in the mask, optional characters are represented as leading blanks. If a '!' character is not present, optional characters are represented as trailing blanks.

>	If a '>' character appears in the mask, all characters that follow are in uppercase until the end of the mask or until a '<' character is encountered.

<	If a '<' character appears in the mask, all characters that follow are in lowercase until the end of the mask or until a '>' character is encountered.

<>	If these two characters appear together in a mask, no case checking is done and the data is formatted with the case the user uses to enter the data.

\	The character that follows a '\' character is a literal character. Use this character to include any of the mask special characters as literal characters in the data.

L	The 'L' character forces a mandatory alphabetic character in this position. For the US, this is A-Z, a-z.

l	The 'l' character allows an optional alphabetic character in this position.

A	The 'A' character forces a mandatory alphanumeric character in this position. For the US, this is A-Z, a-z, 0-9.

a	The 'a' character allows an optional alphanumeric character in this position.

C	The 'C' character forces a mandatory arbitrary character in this position.

c	The 'c' character allows an optional arbitrary character in this position.

0	The '0' (zero) character forces a mandatory numeric character only in this position.

9	The '9' character allows an optional numeric character in this position.

#	The '#' character allows an optional numeric character or a plus or minus sign in this position.

:	The ':' character is used to separate hours, minutes, and seconds within time value strings. If the character that separates hours, minutes, and seconds is different in the regional settings of the Control Panel utility on your computer system, that character is used instead.

/	The '/' character is used to separate months, days, and years in date value strings. If the character that separates months, days, and years is different in the regional settings of the Control Panel utility on your computer system, that character is used instead.

;	The ';' character is used to separate the three fields of the mask.

_	The '_' character automatically inserts forced spaces into the text. When the user enters characters in the field, the cursor skips the _ character.

Any character that does not appear in the preceding table can appear in the first part of the mask as a literal character. Literal characters are copied exactly in the edit control. They are inserted automatically, and the cursor skips over them during editing. The special mask characters can also appear as literal characters if preceded by a backslash character (\).

The second field of the mask is a single character that indicates whether literal characters from the mask should be included as part of the text.

MASK Parameter: Advanced Use

If the contents of a MASK parameter starts with an ampersand character, it is treated as an advanced mask, so no character-by-character validation is done, and the contents are parsed in a different way. Characters following an ampersand up to an equal sign (or the end of the parameter) are treated as a keyword. Depending upon a keyword, the contents of an EDIT element can be checked for one of the following conditions

Keyword	Condition

URL	It is a valid URL

EMAIL	It is a valid e-mail address

DATA	The data is the same as that of a given control. Useful for validating whether a password has been properly confirmed. E.g. MASK="&DATA=UserPasswordAgain=Password is not properly confirmed" compares the string entered by the user in an EDIT field named "UserPasswordAgain" and, if the two strings are not byte-for-byte equal, displays a "Password is not properly confirmed" error box.

REGEX	Matches given regular expression. E.g. MASK="&REGEX=^[a-fA-F0-9]{8}$" matches a string of exactly eight alphanumeric characters.

MANDATORY	Value cannot be empty. If a user leaves the field empty, an error box is displayed.

Example

Below is content of a sample TBC-file that can be used to receive a currency trend for a stated period. The screen form contains a drop-down list (COMBOBOX) for selecting the currency type and fields for date input (EDIT).

-----BEGIN PGP SIGNED MESSAGE-----

MSG FORMTITLE="Currency Rate Request"

MSG TO="Client-Bank <client-bank@bank.com>"

MSG SUBJ="Client-Bank"

MSG PRIORITY="High"

MSG FORMWIDTH=260

MSG FORMHEIGHT=190

MSG ENCRYPT=ON

MSG SIGN=ON

HIDDEN NAME="service" VALUE="getcurrencytrend"

LABEL CAPTION="&Currency"  X=16 Y=8 FOCUSNAME="iso"

COMBOBOX NAME="iso"   X=16 Y=24 WIDTH=120

COMBOBOX NAME="iso"   ITEM="MDL","Moldavian Leu"

COMBOBOX NAME="iso"   ITEM="USD","US Dollar"

COMBOBOX NAME="iso"   ITEM="RUR","Russian Rouble"

COMBOBOX NAME="iso"   ITEM="UAH","Ukrainean Hr."

COMBOBOX NAME="iso"   ITEM="FIM","Finnish Mark"

COMBOBOX NAME="iso"   ITEM="DEM","Deutche Mark"

COMBOBOX NAME="iso"   ITEM="GBP","GB Pound"

LABEL CAPTION="&Starting Date" X=154 Y=8 FOCUSNAME="date1"

EDIT NAME="date1"              X=154 Y=24

EDIT NAME="date1"              MASK="00/00/0000" VALUE="01011996"

LABEL CAPTION="&Ending Date"   X=154 Y=52 FOCUSNAME="date2"

EDIT NAME="date2"              X=154 Y=68

EDIT NAME="date2"              MASK="00/00/0000" VALUE="01011999"

SUBMIT CAPTION="OK"            X=60 Y=112

CANCEL CAPTION="Cancel"        X=154 Y=112

-----BEGIN PGP SIGNATURE-----

iQDVAwUANfjoiRQeqwtQAYtzAQHkIQX+JhO61HCBfVw5VF3KqQhpApmOPhk2gEKz

C7qkNwpx7lexjbZvTVNGNfxTk7cTx5AxSFiUV32JH9WPm9fuJ5/bXIfWojDnaYbi

OM/BqS2KykFyoiuy+KULji10oRTt1jdC0Yqyv+OMgo2RuMwI0QhUozpHlVvkEHkk

r3acZ3NVIjBZHdW0I4YCjA3FKxBQmoFsQg9/ndjeE2lHZTCtLK2Kue036PeSCJq1

JWwVgWwT0JfhfFMXjj5tZm7pspNaGLst

=FBRX

-----END PGP SIGNATURE-----

When the client clicks the OK button, The Bat! generates the following request line:

service=getcurrencytrend&iso=USD&date1=01011996&date2=01011999

Since the values of the ENCRYPT and SIGN parameters of the MSG keyword are set to ON, this string will be signed and encrypted before being sent to the server via e-mail (to client-bank@bank.com). The e-mail message body will look something like this:

-----BEGIN PGP MESSAGE-----

hMwDFB6rC1ABi3MBBgBuPwdXPA/obgJJ/fcjDSqO7oh820EHlKpA5mzbYSwg/qWg

wYvNO/iJq4mofSfUnwozK3S5dD4zSeNcEqzQzw3ZZpE5D8aLOlNRAKlRh2ZIfN4W

6pmLJrhcX/GvsH667YUfL97r8LCWbaBtYI8D85ZluPSNGzt8AIgjIEZLKaAcq6yD

eYpO5GpxvvDvT8Vb80QnUZW5kTX9MGFg+gtUGqcb3f3dibyewWZfjndhkjj4Br4I

QLQ5v0mjx76lqxhbi5qmAAABM3PfOx1lpLE7VkHCTuQSPsm09a69rjQqgKimOPxj

hcH8wKXAi2FYDQ8wY8iszRZ9IeDHJtqOsdr0vUltT0Mj0jGvWi1Jb/jFOZ0jW/2J

k1uFMo5Dy/gaGQjjCIZvRT2dWy7CQ67vnegTi2zsvMAPM6/Bz7qTA6lsMMY88E9p

4qDlcN6OZIlY8DGaExcIDpoZwPChgIQfA55VQyNfN5YKzfBxCmtqSWbbLFh7WnkR

8FBLi9E8rPGg2jmzfAn1CczYnlfXinHtuAKmxmt3m3bOyNv5SGmMz+9WWhWIBH8Q

XIBXrfH2yDDldKwkyj0tsjeXs6LFS7D/kMCdBNM1FClWw1EftTBbdwL0ykDX9Z6f

NS6fQxYJxGrfAMp7hSaGydrenSKEviAy5o6HyjBxoCqQLGKdsWQ=

=wflO

-----END PGP MESSAGE-----

Upon reception of the message, the server decrypts it, verifies the digital signature, extracts the request line, parses it and sends the currency trend back to the user.

If the TBC-file contained the following strings...

MSG TPL=" Service : $service$"

MSG TPL="Currency : $iso$"

MSG TPL="   Start : $date1$"

MSG TPL="     End : $date2$"

...then the query has been sent in a human-readable format, and the decrypted message body would have looked like:

 Service : getcurrencytrend

Currency : MDL

   Start : 01.01.1996

     End : 01.01.1999

If the TBC-file had contained the following strings...

MSG NFO="This message contains your currency rates request"

MSG NFO="that will be sent to the bank. It is PGP-encrypted"

MSG NFO="to protect sensitive information. When you are online"

MSG NFO="press <Shift+F2> (Send Queued Mail item of Account menu)"

MSG NFO="to send the message."

... the message sent to the server would have looked like:

This message contains your currency rates request

that will be sent to the bank. It is PGP-encrypted

to protect sensitive information. When you are online

press <Shift+F2> (Send Queued Mail item of Account menu)

to send the message."

-----BEGIN PGP MESSAGE-----

hMwDFB6rC1ABi3MBBgBuPwdXPA/obgJJ/fcjDSqO7oh820EHlKpA5mzbYSwg/qWg

wYvNO/iJq4mofSfUnwozK3S5dD4zSeNcEqzQzw3ZZpE5D8aLOlNRAKlRh2ZIfN4W

6pmLJrhcX/GvsH667YUfL97r8LCWbaBtYI8D85ZluPSNGzt8AIgjIEZLKaAcq6yD

eYpO5GpxvvDvT8Vb80QnUZW5kTX9MGFg+gtUGqcb3f3dibyewWZfjndhkjj4Br4I

QLQ5v0mjx76lqxhbi5qmAAABM3PfOx1lpLE7VkHCTuQSPsm09a69rjQqgKimOPxj

hcH8wKXAi2FYDQ8wY8iszRZ9IeDHJtqOsdr0vUltT0Mj0jGvWi1Jb/jFOZ0jW/2J

k1uFMo5Dy/gaGQjjCIZvRT2dWy7CQ67vnegTi2zsvMAPM6/Bz7qTA6lsMMY88E9p

4qDlcN6OZIlY8DGaExcIDpoZwPChgIQfA55VQyNfN5YKzfBxCmtqSWbbLFh7WnkR

8FBLi9E8rPGg2jmzfAn1CczYnlfXinHtuAKmxmt3m3bOyNv5SGmMz+9WWhWIBH8Q

XIBXrfH2yDDldKwkyj0tsjeXs6LFS7D/kMCdBNM1FClWw1EftTBbdwL0ykDX9Z6f

NS6fQxYJxGrfAMp7hSaGydrenSKEviAy5o6HyjBxoCqQLGKdsWQ=

=wflO

-----END PGP MESSAGE-----


Hardware security tokens

Note: available in Ritlabs AuthenticBat! and Ritlabs SecureBat! only

Most computers and networks use simple usernames and passwords to protect themselves. But passwords alone do not provide adequate protection - they are all too easily shared or guessed. Hardware security tokens have been specifically designed as portable and secure authentication tokens that address the password replacement needs of both users and systems administrators.

The hardware token contains an integrated circuit with a processor, non-volatile random access memory and a USB interface to a PC. It provides the security of smart cards without the hassle and cost of a reader. The token is small and lightweight, making it easy to carry on a key chain or in a daily planner.

The token is a portable two-factor authentication token ideally suited for email security.

Each token contains a unique 64-bit factory-installed serial number that differentiates an individual token from all other tokens. A token also has a customisable friendly name to differentiate them in a more convenient and friendly way, e.g. "Bob's token."

A token can be in one of three security states: Security Officer State, User Security State and Guest Security State. The security state of the token defines what kinds of actions it can be used to perform. Once plugged in, the token sets itself to Guest Security State until the User PIN or Security Officer (SO) PIN has been entered and verified.


Customising a New Hardware Security Token
Customising a New Token

Note: available in Ritlabs AuthenticBat! and Ritlabs SecureBat! only

If you received a hardware security token from your system administrator, simply follow the instructions provided by the administrator. You will also receive a User PIN (Personal Identification Number) for your token.

If you received a factory-initialised token, you should first change the User PIN and SO PIN. The token is shipped from the factory with the following settings: User PIN: 12345678, SO PIN: rainbow.


Security Officer PIN

Note: available in Ritlabs AuthenticBat! and Ritlabs SecureBat! only

The Security Officer (usually a system administrator) is the person who is entrusted with initialising and configuring the token. The token is placed in the Security Officer State when the Security Officer (SO) PIN has been entered and verified. This is the highest-level security state. When the SO PIN has been entered and verified and the token is in the SO state, in addition to performing actions are only available to the Security Officer, any actions that are valid for the User Security State can also be performed.

The person acting as Security Officer can configure the token to insist upon entry of the user PIN to perform certain actions. The Security Officer can also define the maximum number of times invalid user PINs can be entered before the user is blocked from entering a PIN. Once a user is blocked from entering a user PIN, only the Security Officer can reset the token to unblock user PIN entry.

Warning! Since the SO PIN offers the highest level of security, if a Security Officer forgets the SO PIN, the SO PIN cannot be retrieved from the token, and the token cannot be configured.


User PIN

Note: available in Ritlabs AuthenticBat! and Ritlabs SecureBat! only

The hardware security token is placed in the User Security State when the user PIN has been entered and verified. Users are able to set and update their own user PINs.

When a user enters an invalid user PIN, a token counter decrements. The counter is reset when a valid user PIN is again entered, but if the counter decrements to zero, the user is blocked from entering a user PIN. Only the Security Officer can reset the token so that user PINs can again be entered. The factory-default value for the counter is 5.


Using hardware security tokens for POP3/SMTP Authentication
Using tokens for POP3/SMTP Authentication

Note: available in Ritlabs AuthenticBat! and Ritlabs SecureBat! only

In Account Properties, select the Transport tab and click the Authentication button in the Send Mail or Receive Mail group box. If the hardware security token driver and the API have been properly installed on your computer, you will see a selectable checkbox for the security token: Token MD-5 CRAM-HMAC Challenge/Response in the Mail Retrieval (POP3) Authentication configuration window or a Store password on token option in the Mail Transmission (SMTP) Authentication configuration window.

Once the security token checkbox has been ticked, the Authentication configuration window will change its content to display two new group boxes:

The "Token to Use" group box displays the serial number and friendly name of the token selected to perform POP3 or SMTP authentication for that account. The serial number of the selected token is stored in the account configuration file. The Bat! won't perform authentication with that account using a token with a different serial number unless you click the "Browse" button and select another token. In order to display the friendly name, The Bat! requires that the token with a given serial number is inserted and available (i.e. it is not in use by another application), because the friendly name is retrieved directly from the token. If the friendly name can't be displayed (e.g. the token with a selected serial number wasn't plugged in or it was unavailable), you can try to resolve the problem (e.g. plug in the token with the valid serial number) and press the "Refresh" button to retry the attempt to display the friendly name.

The "Token Password" group box offers three buttons to Set, Change or Remove a password that is stored on the token. Once set, the password can only be used for authentication with that account, but it cannot be retrieved. However, the password can be changed (replaced by another password when, for instance,  the server administrator has assigned a new password for your account) or removed (if you no longer wish to use this token for authentication with that account).


Browsing for a hardware security token
Browsing for a token

Note: available in Ritlabs AuthenticBat! and Ritlabs SecureBat! only

There can be several hardware security tokens plugged into your computer. You may however choose which token to use for secure POP3/SMTP authentication for a specific account.

When you 'browse' for a token to use, you will see a list of available (plugged in) tokens. The tokens that are plugged in but currently exclusively used by other applications are also displayed, but are not available for selection, editing or viewing. You can however press the "Refresh" button to update the current status of the tokens in the list, e.g. to see whether an application that was previously using a particular token has released ownership, making it available for The Bat!

When a token is available, you can click the "View" button to see its technical specification and the amount of available token memory. The total amount of memory depends on which make and model of token is used.

Clicking the "Edit" button in a list of available tokens invokes the built-in Token Editor.


Editing a hardware security token
Editing a token

Note: available in Ritlabs AuthenticBat! and Ritlabs SecureBat! only

The Bat! has its own, built-in Token Editor which can be invoked while browsing a list of available hardware security tokens. This list appears when you select a token during the installation of SecureBat!, or when you configuring the hardware authentication options in the Account Properties dialog.

While the Token Editor is a tool intended mostly for use by Security Officers (persons authorised to perform Security Officer State operations), it also allows the users (persons authorised to perform User Security State operations) to change the User PIN.

The Security Officer can Set Token Name, Change Security Officer PIN and Unblock User PIN.

The users can Change the User PIN.


Change User PIN

Note: available in Ritlabs AuthenticBat! and Ritlabs SecureBat! only

You can change the User PIN from the Token Editor window.

The "Change User PIN" button allows you to change the User PIN. You will be first asked to enter the current User PIN. The factory default User PIN is 12345678. Next, you will be asked to enter the new PIN and to confirm it by typing it again. Type a number from one to eight digits (you may only use the characters 0-9).


Set Token Name

Note: available in Ritlabs AuthenticBat! and Ritlabs SecureBat! only

You can assign any particular name to a token in the Token Editor window.

The "Set Token Name" button allows you to set a friendly name for the hardware security token. Type in a short description to give the token a name, like "Bob's token." You can enter up to 16 alphanumeric characters.


Change Security Officer PIN

Note: available in Ritlabs AuthenticBat! and Ritlabs SecureBat! only

You can change the Security Officer PIN from the Token Editor window.

The "Change Security Officer PIN" button allows you (or the Security Officer) to change the SO PIN. You will first be asked to enter the current SO PIN. The factory default SO PIN is rainbow. Next, you will be asked to enter the new SO PIN and to confirm it by typing it again. Type a PIN consisting of from 6 to 25 letters or numbers.


Unblock User PIN

Note: available in Ritlabs AuthenticBat! and Ritlabs SecureBat! only

You can unblock the User PIN in the Token Editor window.

The "Unblock User PIN" button allows the Security Officer to unblock the User PIN after the retry counter has been decremented to zero, or if the User has forgotten the PIN. To unblock the User PIN you must create a new user PIN for the token. You will be first asked to enter the current Security Officer PIN. Next, you will be asked to enter the new PIN and to confirm it by typing it again. Type a number consisting of from one to eight digits (you may only use the characters 0-9).


Running Ritlabs SecureBat!

Note: available in Ritlabs SecureBat! only

When the user starts Ritlabs SecureBat!, the program looks for the token that contains the assigned ID, reads the ID from the token, and uses the 128-bit encryption key from that ID for on-the-fly encryption of the message base, address books and configuration files. Make sure that the token is plugged in while working with Ritlabs SecureBat! Once the token is unplugged, the program hides all its windows and prompts the user, asking whether they want to exit (loosing changes) or to plug the token back and continue working with Ritlabs SecureBat!. The user may, however, use this feature as an emergency exit from the program.


SecureBat! ID

Note: available in Ritlabs SecureBat! only

SecureBat! ID is a small record that is used as a key for transparent, on-the-fly encryption of Ritlabs SecureBat! operations. Each ID consists of three components: a 128-bit encryption key, a distinctive User Name and a textual Description. The IDs are stored on hardware security tokens and retrieved from the tokens by Ritlabs SecureBat! at start-up. The IDs may also be archived by the Security Officer in the Token Manager ID store file.


Assigning the ID

Note: available in Ritlabs SecureBat! only

The Ritlabs SecureBat! installer prompts the user to assign an ID from a token to the newly installed copy. Once installed, Ritlabs SecureBat! is permanently tied to the User Name of a specific ID, and it is not possible to reassign another ID to the existing Ritlabs SecureBat!. The 128-bit encryption key from the assigned ID is used for on-the-fly encryption of Ritlabs SecureBat! operations.


Installing SecureBat!

Note: available in Ritlabs SecureBat! only

The Security Officer does not need to install each copy of Ritlabs SecureBat! - all installation steps can be easily performed by the users. During the installation, a user assigns an ID to Ritlabs SecureBat! and this ID will be used for all Ritlabs SecureBat! operations. To assign an ID, the user should first select a token and then choose an ID stored on that token. After this assignment has been made, the installation continues.


Selecting a Token

Note: available in Ritlabs SecureBat! only

Once the user runs the installer, a window appears that prompts the user to Select Token. The window displays a list of all inserted tokens. In most cases, only one token is inserted, however, the window shows the serial number and the friendly name for each currently inserted token. It helps to more clearly identify the required token and avoid confusion when an inappropriate token has been inserted by accident.


Selecting an ID from a Token

Note: available in Ritlabs SecureBat! only

When the user has selected a token from the list, Ritlabs SecureBat! displays all of the IDs that were copied to the selected token by the Security Officer. The User Name and the Description of each ID are listed. Please note that the token must contain at least one ID. Whichever ID is selected is then assigned and used to continue the installation. It is extremely important to understand that it is not possible to reassign another ID to the Ritlabs SecureBat! after this point so double check carefully when selecting an ID.


Common errors
Common Problems

Mail cannot be sent

- Has your connection to the Internet been established?

- Make sure that the TCP/IP protocol is correctly installed on your system.

- Check the network or modem cable connections to your computer

- Does your Internet Service provider have SMTP and POP3 servers?

- Is the logon name and password for your SMTP server correct?

- Does your ISP require SMTP authorisation such as POP before SMTP?

- If all of the above are in place and correctly set up but the problem persists, contact your network administrator or Internet Service provider.

Message text is unreadable

Check that you are using the correct character translation table. If you are, check the message header for the field named "Content-transfer-encoding" - it is possible that the message is encoded using a method unknown to The Bat!. In this case, you will have to ask the sender to re-send the message again using either base64 or quoted-printable encoding.

How can I copy a contact to another address book group?

To place the same contact into multiple address book groups, do the following:

Right-click on the contact

Select 'Properties'

Click the ellipsis button (...) next to the 'Groups' field on the 'General' tab.

Put a checkmark in the box of each group you want this contact to appear in.

The nice thing about this feature, is that you only have to change one contact's entry, and all the rest will be automatically updated. However, if the contact has different entries depending on which group they are in, then you will need to create a new/separate contact entry for that group.

How can I create multi-lined sigs / cookies

If you'd like to create a signature such as this:

When planets run around in circles, we say they are orbiting.

When people do it, we say they are crazy.

Then your cookie line needs to look like this:

When planets run around in circles, we say they are orbiting.\nWhen people do it, we say they are crazy.

Notice the '\n', which represents a new line.

Making TB work with browsers.

Making The Bat! the default mailer for Netscape?

Download <A href="nsproto.exe">nsproto.exe</A> (1.1 MB)

Install and execute

Make a new protocol:

Application: c:\program files\the bat!\thebat.exe

Template: <A href="mailto:%a">mailto:%a</A>

Save as: mailto

Register

Making The Bat! the default mailer for Opera:

Go to Opera Preferences / Mail under external mail application.

Enter this string: "C:\Program Files\The Bat!\thebat.exe" mailto:

When I use '%' characters in a template, they disappear?

When using '%' characters in a template or a quick template, you must double it up otherwise it disappears when The Bat! tries to process it as a non-existent macro, i.e.: "100%% The Bat! generated email".

Error "This version of PGP requires an Administration Preferences file..."

When I try to sign or encrypt a message, I get the following error:

This version of PGP requires an Administration Preferences file. This file is either corrupt or not present on your computer. Please contact your Security Administrator.

OpenPGP is trying to open a file called pgp_admin.prf. You must create this (empty) file and save it in your OpenPGP directory. Then it will work without any error message.

How can I print a range of pages? The option is greyed out!

The option is greyed out only if the message consists of a single page. If the message is two pages long or more, it will be normally accessible.

How can I re-dock the Quicksearch toolbar?

Move your floating Quicksearch toolbar - roughly to the position of the top toolbar. Then CLOSE DOWN The Bat, run Regedit and browse down to HKEY_CURRENT_USER\Software\RIT\The Bat!\Toolbars\tbSearch

Double click on DockedTo - and change the "+" entry to "MsgDock"

Close down Regedit, restart TheBat - and the Quicksearch toolbar should be located at the top of the folder list.

When I receive HTML mail, the pictures don't show.

The Bat! does not download images that are not sent with the message.

It is widely considered that this is a good thing. The downloading of images should be the job of a browser and it can become a security problem when that functionality is given to an off-line email reader.

The work-around if you really want to see these images is to double-click on the HTML attachment to view it in your favourite web browser.

How do I get rid of Re[2]: numbering in the subject?

This is easy to do by adding the <b>%SINGLERE</b> macro to your templates as required. It doesn't matter where you put this macro within the template. It works the same at the beginning or at the end.

Why do my paragraphs run together when I try to start a new one?

This is because you have auto-format turned on in your editor preferences. Auto-format will automatically reflow the text within a paragraph. A paragraph in The Bat! ends with a completely blank line. If you attempt to type a new paragraph without a preceding blank line then auto-format will join it to the previous paragraph. If you don't want to leave blank lines then turn off auto-format

Become familiar with the keyboard shortcut to turn auto-format on and off, which is <Shift+Ctrl+F>.

Leave auto-format enabled and press <Shift+Ctrl+F>to turn it off when you want to control formatting more strictly, for instance when typing a list of things.

When I add or delete words in a paragraph, the lines don't automatically wrap to keep the paragraph formatted.

Place your cursor somewhere inside the paragraph and press <Alt+L>, <Alt+C>, <Alt+R>, <Alt+J> for Left Justify, Centered, Right Justified, Justified respectively. If you place the cursor inside the paragraph with the mouse, you must hit one of the arrow keys at least once to get the whole paragraph to reformat, otherwise it will only format the single line in which your cursor was positioned.

How can I reorganise my folders

There are three ways to do this depending on what exactly you want to do.

- Alphabetically / By # of new messages / By # of total messages: to reorganize your folders to any of these three sorts, just click the header at the top of the respective column. e.g. to sort by # of new messages, click the header 'New'.

- To move a folder within the same hierarchy, click on the folder to move and while still holding down the mouse button, also hold down the <Alt> key. Drag the folder to its new location.

- To move a folder to within another folder (make it a subfolder), click on the folder to move and while still holding down the mouse button, also hold down the <Ctrl> and <Alt> keys. Drag the folder on top of the folder you want it to reside in.

I'm missing some folders (and I didn't delete them). How do I get them back?

With the account selected that is missing folders, simultaneously press the <Ctrl+Alt+Shift+L> keys. This will force The Bat! to search for all folders and add them to the folder tree.

How can I copy a batch of filters between accounts?

Currently, you can do it in the following (slightly tricky) way:

Open a notepad (or other text editor) window and open the Sorting Office then use the following steps for each filter:

1. In the Sorting Office, use the Copy (<Ctrl+C> or <Ctrl+Ins>) command

2. Switch to Notepad and use the Paste (<Ctrl+V> or <Shift+Ins>) command

3. Switch back to the Sorting Office and repeat from step 1 for other filters.

When you have all the filters you want in the Notepad, select the entire text and copy it into the Clipboard. Select the other account, choose the appropriate filter set and use the Paste command.


Edit Address Entry
Editing an Address Entry

The "Edit Address Entry" dialog box is used to enter and amend the various properties pertaining to an entry in the Address book or your own address entry (vCard) in the Account Properties.

Most importantly, this is where you can set and change the name and email address of the individual and any custom message templates associated with this address. You can also editS/MIME certificates associated with this address entry. See also Address Book for more information.


Edit Address Book Properties

"Edit Address Book Properties" dialog allows you to change the name or location of the current Address Book. It also allows you to select whether or not this address book should be used as the default for Add/Delete operations.


No help available

There is no additional documentation available for this topic. If you are having difficulty working out how to use this facility, you can check on the on-line FAQ or join one of The Bat! user discussion lists to get peer help on this subject.

See http://www.ritlabs.com/the_bat/support.html for more information.


Memo fields are simple text fields in which you can place any text you wish as a memory jogger, reminder or note on the item to which the memo belongs


You are about to delete a folder. Please choose what you want to do with the messages stored in this folder and its sub-folders:

Move To Trash -	Store all messages of the deleted folder(s) in the account's Trash folder, then delete message base. Please note that using this method may take a long time for highly populated folders.
Wipe -	Completely remove the folder (an its sub-folders) with its message base from the disk. You will not be able to recover messages from deleted folders. Be careful choosing this method!
Leave message base files intact -	Simply remove the folder's sub-tree from the account's folder list, message base files stay on the disk. It is possible to add the folder back in future by creating a folder with the same name and home directory.


Tools menu
The Tools Menu

Use the tools menu to access some of the more in-depth extra functionality of The Bat!

This includes the Address Book, the Message Finder, the Maintenance Centre and OpenPGP settings.


Create Mail Filter

The Create Mail Filter dialog box is a quick way to set up a new Sorting Office Filter filter for the current message.

Name - Enter an applicable name for this sorting office rule, one that will make its relevance obvious to you when seen in the list of Filters in the sorting office.

Detect by - Select which message fields should be used for match detection. You can choose from Sender, Subject and Recipient as to which fields should be scanned and matched with which signal strings. By default, these are pre-filled for you with details from the current message.

Use for - Select whether this rule is for Incoming, Outgoing, Read or Replied messages.

Move to folder - Choose a destination folder for filtered messages.

Override existing filters - Check this option if you want the new filtered to be created at the top of the current set of filters. Leave this option unchecked if you want the filter to appear at the end of the current set of filters.

You can click on OK to create the filter and close the Create mail filter dialog box.

Click on Edit if you want to create the filter and then further modify the newly created filter using the full Sorting Office filter editor to select advanced options and actions for the new filter.

Click on Cancel to discard the information without creating a new filter.


Advanced filtering conditions

"Advanced filtering conditions" give you access to extra settings which must be in force for a filter to come into effect. These conditions include:

Screen saver must be, which allows you to specify filters that only occur when the screen saver is active or inactive. The default is "in any state", which means that the filter will operate regardless of the state of the screen saver. For example, when the screen saver is active, you may want The Bat! to alert you to certain incoming messages by playing a particular WAV file and execute a program which turns of the screen saver. Another example of how this can be used to good effect is that an automated reply can be sent to known "urgent" messages when the screen saver is active saying that "The operator is not available right now and will deal with your request upon their return".

The Message priority is option allows you to additionally filter on High and/or Normal and/or Low priority messages.

You can filter on message Parked status, message Flagged status, message Colour group, Size, and Age.

You can also specify that Addresses must / must not be listed in the address book for one of the Sender, First recipient, All recipients, Sender and first recipient, Sender and all recipients. This is useful for filters which add or remove names and addresses to/from the address book.

The final additional condition is that the filter can be restricted to only act within specific hours of the day.


Importing Email Messages
Importing/Exporting Email Messages

The Bat! has two native import/export formats for email messages. These are .MSG and UNIX mailbox.

.MSG format is a method of storing single messages in transportable files which can be imported and/or opened by many different types of system. The .MSG format is essentially a plain text dump of the entire message content including RFC-822 headers (kludges).

UNIX mailbox format is a method of representing a whole stream of messages in a single file. Again, the UNIX mailbox format can be read by other systems and also by The Bat! itself, providing a useful way to export and import single folders or batches of messages.

The message Import / Export functions can be accessed through the main menu "Tools | Import messages" and "Tools | Export messages" options.

You can also import messages from other email client software with The Bat!'s built in import wizard. The wizard is able to recognise the following formats:

•	Microsoft Outlook Express v4.xx

•	Microsoft Outlook Express v5.0

•	Netscape Communicator v4.xx

•	Netscape Mail v2.xx/3.xx

•	Eudora Lite/Pro

•	Pegasus Mail v2.xx or 3.xx

To import from Microsoft Outlook, first export the messages to Outlook Express format. You can then import from there using the import wizard. If the format you want to import from isn't covered by the Wizard then it is possible that you can export from the other system into standard UNIX format, which is one of The Bat!'s standard import formats.


MIME stands for Multipurpose Internet Mail Extensions. It is used for encoding messages and attachments. When you use MIME to forward a message, you effectively add the message as an attachment. Such an attached message (or, more often, group of messages) can be referred to as a MIME digest.

The mode of message forwarding is determined in your account configuration for forward. Whichever method is your selected default, you can use the alternative forwarding method in real time by selecting the "Message | Specials | Alternative forward" option.


Folder Tree

The Folder Tree shows the folders defined for this account in a tree structure.

To re-position a folder within the account's hierarchy, press and hold the Alt key and then use drag-and-drop to move the desired folder. This will move a folder next to the folder onto which it is dropped in the account folder tree. To drop a folder into another folder and make it appear as a sub-folder, use <Ctrl+Alt> while dragging the folder.

Alternatively use the <Shift-Ctrl-Arrow> keys to move folders up, down, in and out within the tree structure.


Sound Settings

This is where you can set specific Sound Settings for this account. These settings are described in more detail under New mail Notification (Sound).


URL Highlights

URL references such as www.ritlabs.com and mail@example.com are automatically highlighted and "activated" as you type them in the message editor or as they appear in a received email.

You can double click on the highlighted URL reference to "launch" it. If the URL is a web (or http:) reference, it will open in your browser. If it is an email (or mailto:) reference then a new message window will open with the address already entered in the To: header field.

Not all URLs are easily distinguished. In some cases, the only way of URLs can be clearly distinguished from other text is when using HTML. If you want to open a URL which hasn't been properly highlighted, you can select the URL manually, invoke the context popup menu (click the right mouse button or press <Alt+F10> or menu button on an MS Keyboard) and choose the "Open URL" option.

N.B. If you use Internet Explorer, you can press <Shift> while clicking the URL to open the URL in a new browser window without affecting any which may already be open.


Threading

 Message lists can be "threaded" to show which messages are connected to each other and improve the readability of, for instance, whole topics within folders.

You can thread messages in the message list by Reference (<Alt+1>), Subject (<Alt+2>), From (<Alt+3>) and To (<Alt+4>) - and, of course, unthreaded (<Alt+0>).

The first of these is the default and standard threading method. It relies on the use and presence two specific message headers: 'In-Reply-To:' and 'References:'. These message headers contain "Message ID" strings. The Bat! can thread together message which refer back to the ID(s) of earlier messages in the topic.

The other threading methods are more simple in approach and involve chaining together messages with matching Subjects, To or From values in chronological order.

To open all threads in a folder message list press <Shift+Ctrl+*>. To open / close all branches of the current thread, use <Shift+Ctrl+Plus/Minus>. To open and close threads use < Plus/Minus> and to toggle threads open or closed you can use <Shift+Space>, <Ctrl+Space> or <Alt+Space>.


Miscellaneous commands
Miscellaneous Editor Commands

Action	Key combination
Save the message and continue editing	Ctrl+S
Save the message in the queue and close the edit window	Shift+F2
Send the message immediately	F2 or Ctrl+Enter
Undo	Alt+Backspace
Place a position marker in the text	Ctrl+K n (n=0..9)
Return to a position marker	Ctrl+Q n (n=0..9)
Insert the Current Date	Ctrl+Q D
Insert the Current Time	Ctrl+Q T
Uppercase the Current Word	Ctrl+[
Lowercase the Current Word	Ctrl+]
Capitalise the first character of the Current Word	Ctrl+/
Search for a string	Ctrl+Q F
Search and replace	Ctrl+Q A
Repeat the last search	Ctrl+L
Cancel operation	Esc

See also:

Block and formatting commands.

Insertion and deletion commands.

Cursor movement commands.


A standard "cut mark" or "signature delimiter" is used to indicate where message text ends and a removable signature begins. The Bat! will recognise this mark when you reply to a message and will cut away the mark and any text below it from the original text. This cut mark is a simple sequence comprising a new line, two dashes, a space and a new line. Like this:

<new line>

--<space><new line>

<new line> means "press return"

<space> means a single press of the space bar.

In an OpenPGP signed message, OpenPGP modifies the cut mark to have a preceding dash and space, i.e.

<new line>

-<space>--<space><new line>

This is by design.


POP
POP3 (Post Office Protocol Version 3) - a "post office" protocol that is used for retrieving mail from a host server by the client. For this particular protocol, mail message exchange is initiated at the client's request.


SMTP
SMTP (Simple Mail Transfer Protocol) - a simple protocol for mail transmission which is widely used on the Internet. The SMTP server's function is to receive mail from other servers and clients, and to deliver mail to other hosts and to its clients' mailboxes.


IMAP4
IMAP4 stands for Internet Message Access Protocol Version 4. It is a method of accessing electronic mail or bulletin board messages that are kept on a (possibly shared) mail server. In other words, it permits a "client" email program to access remote message stores as if they were local. For example, email stored on an IMAP4 server can be manipulated from a desktop computer at home, a workstation at the office, and a notebook computer while travelling, without the need to transfer messages or files back and forth between these computers. In other words, IMAP4 is a superset of POP3 that provides good support for all three modes of remote mailbox access: offline, online, and disconnected.


The name of the e-mail account as it appears in the account tree of the main program window. It may be any combination of characters. The only limitation is that the name must be unique within the program; in other words, there must not be another account with the same name.


The path to the directory where all files related to the given account are stored. This directory is also used for creating default sub-directories. Each mail folder keeps its messages in a MESSAGES.MSB (or MESSAGES.EBB in SecureBat!) file in its mail-folder directory, which by default is placed in the home directory of the account it belongs to.


Click this button if you want to specify another Home directory


Click this button to specify default Home directory


Click this button to perform the next step


Click this button to return to the previous step


The originator's name, which will be put in the header of each message created from this account. For example, John Smith.


The Originator's e-mail address, which will be put in the header of each message created from this account. For example, john.smith@example.com


Organisation to which originator belongs (if any). Example: Mythical Software, Inc.


The name to which replies should be addressed. For example, John Smith.


The address to which replies should be sent. For example, john.smith@example.com


The address of the SMTP server to which all your outgoing e-mail messages from this account will be sent. The address may be represented as a traditional Internet host name (e.g.: mail.ritlabs.com) or as an IP numeric address (e.g. 193.219.214.38).


The address of the POP3 server where the account's mailbox is located. Messages from the Internet are usually accumulated on POP3 servers and may be retrieved from there by the Get new mail command or using the Message Dispatcher. The address may be represented as a traditional Internet host name (e.g.: mail.ritlabs.com) or as an IP numeric address (e.g. 193.219.214.38)


The POP3 user name for access to your mailbox on the server. It is usually, the same as the part of the account's e-mail address before "@" symbol. For example, if the e-mail address is john.smith@ritlabs.com, the user's name will often be john.smith.


The password for logging on to the POP3 server. You may leave this field blank - in this case you will be prompted to enter the password each time you try to receive mail.


If this options is set, your messages will not be deleted from the server after their retrieval. This gives you the advantage of begin able to re-download a message later if you have lost its copy on your machine.


Closes this dialog box without saving the changes you have made.


The To field indicates the primary recipient(s) of a message.


CC (Carbon Copy) recipients of a message are the people you want to "listen in" to the message you are sending to the primary recipient. CC recipients receive the message normally, but they do not see themselves as the primary recipient of the message; nevertheless, all CC recipients are listed in the message header.


Use a BCC (Blind Carbon Copy) if you do not want the primary addressee to know that the message is sent to somebody else. This may be helpful when it is necessary to send a notification message to a large group of people - using BCC will considerably reduce the message size.


"Purge" refers to marking messages as deleted in folders where the messages either exceed the "Keep for nn days" property of the folder or exceed the folder's maximum message count, in which case older messages are marked deleted.


"Compress" is a function that removes messages marked as deleted from the message base files. This should be done periodically to keep used space to a minimum and to reclaim the space freed in purge, delete and filter operations.


Purge

The "Purge" action will result in marking messages as deleted in folders where the messages either exceed the "Keep for nn days" property of the folder or exceed the folder's maximum message count, in which case older messages are marked deleted. This helps you to automatically manage the amount of space your mail base occupies as time goes by.

Purge can be useful, for example, in a folder where you keep weekly price lists, a 7 day purge will make sure that only the current price list is kept.

These messages stay in place, unseen, until the folder is Compressed.


Compress

The "Compress" option removes messages marked as deleted from the message base files. This should be done periodically to keep used space to a minimum and to reclaim the space freed in purge, delete and filter operations.


The Autosave function automatically saves your message while you are editing it after the specified period of time has elapsed. To enable this facility, use the "Options | Editor preferences" dialog.


Reading confirmation is an optional facility for email messages. You can both send and receive messages that require automatic confirmation of having been read. See Reading confirmation and

Confirm Receipt and Reading Confirmation for more information.


Verifying S/MIME signed messages

Whenever you receive an S/MIME signed message, you can immediately see from the S/MIME icon whether the signature is valid ensuring that the information in the message has been sent by an authorised person and has not been changed before it arriving in your mailbox.

You can also double-click on the S/MIME icon to see details of the signature itself.

See also: 	Encrypting S/MIME messages

Signing your message with S/MIME

Decrypting S/MIME-encrypted messages


Select OpenPGP Implementation

Internal (RFC-1991) - An internal implementation of OpenPGP, supporting RSA keys up to 4096 bits with 128-bit IDEA(tm) cipher algorithm and MD-5 hash support. It needs no external executables or plug-ins. Submission Forms only work with this selection. IDEA(tm) algorithm is patented in the following countries: Austria, France, Germany, Italy, Netherlands, Spain, Sweden, Switzerland, United Kingdom, United States. A license must be purchased from MediaCrypt AG for any use of IDEA(tm) for commercial purposes in the above countries. MediaCrypt AG contact information is MediaCrypt AG, Technoparkstrasse 1, 8005 Zurich (Switzerland); Tel.: +41-1-445 3070; Fax: +41-1-445 3071; http://www.mediacrypt.com/; mailto:info@mediacrypt.com.

PGP command line (2.6.3, 6.0.x+) - This mode allows using any command line Win32 PGP executable: PGP 2.6.3, 6.0.x, 6.0.x, 6.5.x, 7.0.x, etc, and compatible. Just make sure that the name of the folder in which PGP.EXE resides is in your system's PATH Environment variable. To use PGP 2.6.3 in this mode, make sure that you have PGPPATH set as specified in the PGP documentation. For more detailed help, consult the PGP User's Guide.

PGP 5.5.x plug-in - To use this mode, you will need to install PGP 5.5.x for Win32. Make sure that you've rebooted your computer after installing PGP. The plug-in (batpgp55.dll) is not part of the standard The Bat! installation and will have to be installed separately.

PGP 6.0.x / 6.5.x plug-in - To use this mode, you will need to install PGP 6.0.2 or 6.5.x. for Win32. Make sure that you've rebooted your computer after PGP installation. The plug-in (batpgp60.dll) is not part of the standard The Bat! installation and will have to be installed separately.

GNU Privacy Guard (GPG) - To use this mode, install the GNU Privacy Guard command line Win32 executable. Make sure that the name of the folder in which GPG.EXE resides is in your system's PATH Environment variable. Refer to the GPG Manual.


File Mask Format
File Filter Format for FILEFILTER

This section describes the format of the file filter for the FILEFILTER keyword.

A file mask or file filter is a file name that usually includes wildcard characters (*.TXT, for example). Only files that match the selected file filter are displayed in the dialog box's list box, and the selected file filter appears in the File Name edit box. To specify a file filter, assign a filter string as the value of the Filter. To create the string, follow these steps:

1	Type some meaningful text that describes the type of file.

2	Type a | character (this is the "pipe" or "or" character).

3	Type the file filter.

Don't put in any spaces around the | character in the string.

Here's an example:

Text files|*.TXT

If you entered the preceding example as the filter, the string "Text files" appears in the List Files of Type drop-down list box when the dialog window appears, the file filter appears in the File Name edit box, and only .TXT files appear in the list box. You can specify multiple file filters so that a list of filters appears in the List Files of Type drop-down list box or in the filter combo box. This allows the user to select from a number of file filters and determine which files are displayed in the list box.

To specify multiple file filters,

1	Create a file filter string as previously shown.

2	Type another file filter in the same way, but separate the second file filter from the first with the | character.

3	Continue adding as many file filters as you like, separating them with the | character. The string can contain up to 255 characters.

Here's an example of three file filters specified as the value of the Filter property:

Text files (*.TXT)|*.TXT|Report files (*.RPT)|*.RPT|Output files (*.OUT)|*.OUT

Now when the dialog box appears, the user can choose from the three file filters that appear in the List Files of Type drop-down list box.

Note that the previous example includes the file filters in parentheses in the text parts. This isn't required, but it's a common convention that helps users understand what to expect when they select a file filter.

You can string multiple wildcard file filters together if you separate them with semicolons:

All supported files|*.TXT;*.RPT;*.OUT


Template Editor

The Bat!'s template editor provides a quick and easy way to edit your templates and quick templates. The template editor window follows the editor settings for the message editor and will obey the same line wrap and auto-format settings.

The template editor window includes a text entry area and a handy "Macros" button to give you quick and easy access to the very comprehensive set of template macros that bring your email messages to life.


Mass Mailing

If you want to send a standard message to a group of people, yet have the message custom written to every person in the group as if they were the only recipient, you can use The Bat!'s mass-mailing features.

Create a Quick Template containing the text of the message and use template macros to create personalised inserts for the message (like first names in greetings, etc.). In the Quick Template editor, tick the "Use for new messages / Mass mailing" box.

In the address book, create a group for the intended recipients for this mass mailing (if you don't already have one).

Once you have at least one mass-mailing quick template defined, the Address Book contains a couple of new menu entries: New message using template and Mass mailing using template. Each of these menu options leads to a list of available mass-mailing quick templates.

First select your recipient group. Then select the option you want (New message or Mass mailing) and that's it - all done!


IMAP (Internet Message Access Protocol) is a method of accessing your e-mail messages directly on a mail server. It allows a client email program to access remote the message store as if was local.


Message Menu

The message menu is the main interface for all message management functions.

Most of the functions are self evident, and generally apply to the currently viewed message.

New	Create a new message

Submit a form	See "Submission Forms" for more details

Reply	Create a reply to the message

Reply to All	Create a reply to the message addressed to all recipients of the original message

Forward	Forward the message to a specific address(es). The message may be sent as quotes or as an attachment (in a MIME envelope). Depending on the account default settings for forwarding. The forwarding template (of 1. the recipient 2. The source folder 3. The account) is used for generating the forwarded message

Re-send	Re-send a copy of the message. This will obey the current setting of the "Send Immediately" option.

Redirect	Open a new copy of the message with no recipient information ready to be sent to a new destination.

Move to folder	Move the message to another folder. The "Move message" dialog box gives you the opportunity to create new folders as required

Copy to folder	Create a copy of the message in another folder. The "Copy message" dialog box gives you the opportunity to create new folders as required

Save As	Save the message to disk. The message is saved using the save message template

Delete	Delete the message

Attachments	A sub menu with options to allow you to handle attachments with options to Open, Save, Delete, Print or Import Keys

Mark as unread	Mark the message as unread

Mark as read	Mark the message as read

Park	Flag this message as parked (or "draft" if the message is in the Outbox)

Unpark	Flag this message as unparked (or "non-draft" if the message is in the Outbox)

Flags	Change the flags on this message (Flagged, Replied, Forwarded/Redirected or Low, Normal, High priority)

Colour Group	Select which Colour Group the message belongs to

Print	Print the message according to the print template

Print Setup	Define the print margins, template, page numbering, fonts and layout for printing messages

Exit	Close The Bat!


View Menu

The view menu is the main interface for all message management functions.

Most of the functions are self evident, and generally apply to the currently viewed message.

Toolbars	Select which toolbars are visible

Message Auto-view	Switch to turn off the message viewer in the main window

Address Auto-view	Switch to open the pop-up address viewer. This window will show the address book entry and any applicable photo of the sender of the currently viewed message

Memo Auto-view	Switch to open the memo view window for the currently viewed message

Log panel	Switch to turn on/off the display of a single line log panel at the bottom of the main window. Use the drop down arrow to the right of the Log Panel to view more information from the log

Attached Files	A submenu to select whether the attachment panel to the left of a message view is shown Automatically,  Always or Hidden

Split Mode	Choose from one of five different window layouts for the main window.

Display	Message filtering for the message list. Choose to display, e.g. Only unread messages, Only messages with attachments, etc.  Advanced filtering is also supported.

Sort by	Choose which column to use for the message list sort order

View threads by	Choose which method to use for message threading

Message Header	Choose which fields to display in the message header section of the message auto-view

Message List Columns	Choose the size, order and which columns to display in the message list for this folder. If the folder is set to "Use the account default column settings" then any changes you make will be applied to all other folders with this setting enabled

RFC-822 headers	Turn on/off display of the RFC-822 headers (aka kludges) at the top of the message body in the message auto-view window

Edit shortcuts	Change which shortcut keys are assigned to which functions

Character set	Choose which character set is used for the message auto-view window


WWW Home Page

The WWW Home Page item of the Help menu of the main window links  you to the RITlabs The Bat! homepage on the Internet where you are able to download new version of The Bat!, learn more about The Bat! features and benefits, read what other people think about The Bat!, get recent The Bat! prices, register a copy of The Bat!, and receive technical support.


The Main Window

The Main Window

This is the main window for The Bat! From here you have easy access to your Account Properties, folder tree, message lists and a message auto viewer.

Click in the image above for more information on specific aspects of the main window.


Account Menu

The Account Menu is the main interface for all account management functions.

Most of the functions are self evident, and generally apply to the currently account.

New...	Create a new account

Delete...	Delete this account

Get New  Mail	Get new any new messages for this account. The default shortcut key for this function is <F2>

Send Queued Mail	Send any messages queued in the OutBox. The default shortcut key for this function is <Shift+F2>

Change POP3 password...	Quick access to change the password used for POP3 Authentication

Set Access Password...	Lock this account with an access password. Use this option to provide / change / clear any access password. The default shortcut key for this function is <Ctrl+F12>

View Log	Show the account event log. This is where to see the full log of events (send and receive) . The default shortcut key for this function is <Shift+Ctrl+A>

Refresh folders	Refresh the folder tree - reloads the message count data. The default shortcut key for this function is <Ctrl+F9>

Dispatch Mail On Server	Activate the Message Dispatcher for either New Messages <Ctrl+F2> or All Messages <Shift+Ctrl+F2>.

Sorting Office / Filters	Open the Sorting Office to edit your account's filters. The default shortcut key for this function is <Shift+Ctrl+S>

Properties...	Change or review the properties for the account.


Options Menu

The Options Menu is the main interface for all The Bat! system-wide options.

Most of the functions are self evident, and generally apply to the currently account.

Preferences...	Opens the main Preferences window
Editor Preferences...	Change the settings for the editor / viewer.
Quick Templates...	Edit the Quick Templates. The default shortcut key for this function is <Shift+Ctrl+Q>
Network & administration	See The Bat! Networking Course and Working in Multi-User EnvironmentIDH_MULTIUSER for more information about how these options are used.
Message list colours...	Define custom message list colours.
XLAT Tables	This is the main entry point for the interface to allow you to load or edit Character Translation Tables.
S/MIME	Set your preferences for the use of S/MIME.
Submission Forms...	Submission Forms - a tool for creating queries that can be automatically processed
Define System Hot-Keys...	Set up the System-Wide Hot-KeyIDH_SYSHOTKEYS functions.
Virus protection	Configure which external virus protection support The Bat! should use.
Language	Select the language to be used for the user interface.


Folder Menu

The Folder Menu is the main interface for all folder management functions.

Most of the functions are self evident, and generally apply to the currently selected folder.

New...	Create a new folder. The default shortcut key for this function is <Ins>
New Common Folder...	Create a new common folder. The default shortcut key for this function is <Alt+Ins>
Delete...	Delete the currently selected folder. You will be given an option to choose how you want to delete the folder (whether to move messages to the Trash folder, remove the message base completely or leave the message base on disk so you can "reconnect" the deleted folder lately)
Browse	Open the folder view window to browse the messages in the selected folder
Compress	Compress the folder's message base file. The Compress function permanently removes any messages from the message base that were previously marked as deleted.
Mark all messages Read	Mark all messages in this folder as read
Empty	Delete all messages from this folder
Refresh	Reload the folder index to refresh the message count and contents of the Message List
Re-filter	Re-apply filters to the messages in this folder. You can choose which filter set (Incoming, Read, Replied, Outgoing) you can apply at this point.
Remove duplicates	Scan this folder for duplicate messages and delete them. Duplicate messages must share the same date and ID headers to be processed as duplicate.
Browse deleted messages	Open this folder in a folder view window which lists messages that have been deleted but not yet expunged from the message base.
Purge+Compress	Purge then compress the message base for this folder.
Check for viruses	Scan all messages in this folder for virus infection
Maintenance Centre	Invoke the Folder Maintenance Centre to perform integrity checking, removing duplicate messages, purging and compressing on multiple folders at once.
Properties...	Change or review the properties for the folder


Help Menu

The Help Menu allows access to this help file and other, more administrative function.

You can enter your registration code through the option in this menu.

You can generate feedback and bug reports using the Feedback submenu here.

Help about will show version information and the "credits" screen.


The Tools Toolbar

The Tools Toolbar gives you access to the main Tools functionality using icon buttons.


The Main Toolbar

The Main Toolbar gives you access to the Main functions of The Bat!

The icon buttons to Get, Send and Create messages have an associated drop down menu, accessed by pressing the small triangle icon to the right of each of the buttons.

For Get and Send, the drop down menu allows you to choose which account(s) the commands will apply to.

For the "Create message" button, the drop down menu contains the addresses marked as "Favourites" from within your address book.

Other functions accessible from the toolbar include the Address Book, Message reply, Reply to all, Forward, Redirect, Find, Print, Save and Delete.


Search Address

The "Search Address" window can be invoked from the Address Book Window <F8>, File | Search menu option <F7>.

This window will allow you to search for a specific address with multiple field matching and advanced logic facilities. You will be able to specify which address books should be used for finding matching records. This includes any associated LDAP address books.


Message Age Limits

You can define "Message Age Limits" to restrict the messages displayed in the Mail Ticker (tm) to only those that have arrived within a certain time frame.

In this way, the ticker can be configured to only inform you of the presence of newer messages.


A message should be displayed only if...

A message should be displayed only if...


Log Panel

This is the account log panel.

The log panel shows the last message added to the account log. For a quick view of recent log entries, click on the drop down icon at the right hand end of the log panel. A list box will popup allowing you to see more of the log.

You can open the Account log window from the Account menu. From the account log window, you can clear the log or restrict the log display to only show highlights. You can also highlight and copy text from this window, should you need to report logged problems to anyone.


Re-Filter Mail Folder

Re-filter a Mail Folder when you have defined a new filter or wish to impose certain manual filters on a folder beyond those filters executed automatically by associated events (Incoming, Read, Reply, Outgoing).


Print Address Book

Print Address Book - this function allows you to print (either selected entries or entire lists) data from your address book in one of the following output formats:

o	Memo

o	Business card

o	Telephone list

o	Address list


Print Setup

Print Setup - this simple looking option hides a powerful section of The Bat! here you can define the page layout to be used for printing messages. You can choose whether or not to number pages and how that numbering should appear. There is a separate template just to handle the presentation of the page number.

This is the General tab of the print setup window. The Template tab allows you to define a complete template to be used for printing messages. Finally, the Font layout tab allows you to pre-define font faces, styles, sizes and colours for various aspects of the printed message, like quoted text and special consideration for printing HTML messages.


Setup Columns

The Setup Columns dialog box is used to configure columns for the message list. You can control which columns are shown, the order they appear in and the size of the columns in pixels.

Access the Setup Columns by right clicking on the message list column headings.


Forward/Redirect of multiple messages

The Forward/Redirect of multiple messages pop-up dialog appears when you try to forward or redirect more than one message at a time.

You are offered the option to process each message individually by opening separate editor windows for each message being handled or to send all messages to a single address.

This should not be confused with the MIME forwarding option.


Find Text

The Find Text tool is used to search for text in a message in the text editor. You can search the whole message or just selected text. You can search from the beginning of the message or from the current cursor position. You can search forwards or backwards. Searches can be case sensitive and restricted to whole words. You can also search using Regular Expressions.

A simpler Find Text tool is available for finding text in a message view window. Searches can be case sensitive and restricted to whole words. You can also search using Regular Expressions. Cursor and block restrictions are not applicable.


Replace Text

The Replace Text tool is used to replace text in a message in the text editor. You can search the whole message or just selected text. You can search from the beginning of the message or from the current cursor position. You can search forwards or backwards. Searches can be case sensitive and restricted to whole words. You can also search using Regular Expressions.


Select Application

The Select Application dialog box is used to provide an application association for an unknown attachment type. If you are trying to open an attachment and there is no association known to the system for that type of file, The Bat! will ask you to select an application to use for opening this kind of attachment.


Edit Group Properties

The Edit Group Properties dialog box allows you to specify how address book groups will behave. Here you can define groups specific templates amongst other things.

See Address book groups for more details as to which options are available and what they are used for.


Edit Colour Group

The Edit Colour Group dialog box allows you to change Colour Group settings for individual message list colour groups.

This dialog box can be invoked from the edit colour groups button of "Edit Message List View Colours" dialog that can be called from the Edit Colour Groups item of "Colour Group" sub-menu of Message Menu of the Main Window.

When creating the colour group you can give it a unique ID or handle. Again this should be a meaningful reminder of its purpose for your own reference.

When editing the settings for a colour group, you can give it a name (one to specify the meaning of that colour group for your own reference).

You can select a Font script to be used in association with this colour group.

Here the dialog splits and gives you access to settings for Normal and Unread messages using a standard tabbed dialog control. For each of these types of message you can set the text colour, the background colour and the font style (bold/italic/underlined/strikeout).


Import Address Book

This is the Import Address Book dialog box, invoked when importing addresses from coma-separated or similar format.

See import address books for more information.


Message Finder

The Message Finder is an excellent resource to have at your disposal. It will hunt down a message for you and find it wherever it may be lurking. To call the message finder, press F7 button in the Main Window or select Search item of the Tools menu.

First the Search for prompt. This is where you can type in what you are looking for. The message finder will accept '&', '|' and '~' special characters to denote AND, OR and NOT operations within the search string. If you need to be more sophisticated with your search string, you can also search using Regular Expressions by turning on the option on the Advanced tab.

The Scope section allows you to specify which areas of the message should be searched. Most of these are pretty self-evident. The only one of these options disjointed from the original message itself is the Memo, which can be added to a message as a kind of post-it note. The other options all restrict the search to specific areas of the message - Sender, Recipient, Subject, Headers and Body and the ubiquitous Anywhere option, which includes all of the other options.

The Look in folders section allows you to quickly specify which accounts and folders should be included when looking for the message you are trying to track down. In order to work with sub-dClick right button of mouse to bring up a popup menu where you can Select All (<Ctrl+A>), Unselect All (<Ctrl+U>), Select including sub-folders (<Ctrl+S>), Unselect including sub-folders (<Ctrl+I>).

The Advanced options allow you to place further constraints on the search. You can look for messages with specific flags (Replied, Read, Unread, Flagged, etc.) or before and/or after a certain date and more besides.


Certificate Passphrases

A certificate passphrase is a secret phrase that protects a private key associated with your certificate from being exposed.

The Bat! has an option to cache certificate passphrases.

Please do not use national characters in certificate passphrases. The Bat! uses components and functions from the Microsoft Windows API that work with the Unicode character set. If there is a configuration problem (e.g. the required input locale not being properly installed in Microsoft Windows), Unicode conversion may fail causing the certificate private keys to become inaccessible. The PFX standard is also used to export certificates with private keys, and using national characters in a passphrase may cause incompatibilities when the certificates are transferred between applications.


Export S/MIME Certificates

You are able to export one or more  selected certificates to a file in order to backup them, to import them to another installation of The Bat! or to other software.

This feature is only available when the Internal Implementation is activated in S/MIME Preferences dialog.

The Bat! doesn't export certificates in  its proprietary format; all of the export formats are well-known standards.

Personal Information Exchange - PKCS #12 (.PFX)

This format conforms to PKCS 12 v1.0: Personal Information Exchange Syntax, developed by RSA Laboratories. It allows the export of a group of certificates as well as their private keys. The private keys are individually shrouded (encrypted) using the same passphrases that  have been used in The Bat!, but the corresponding certificates are not shrouded.

Cryptographic Message Syntax Standard - PKCS #7 (.P7B)

This format conforms to RFC- 2630 (Cryptographic Message Syntax), where a group of certificates can be exported to a file based on a signed message packet, but the packet has no message body and no signature, only the attached certificates. This is the most commonly accepted format, but it isn't suitable for exporting certificates containing private keys. If you are exporting such certificates, the private keys will be stripped from the output file and it will contain only certificates but no private keys.

DER encoded binary X.509 (.CER)

This format only allows you to export a single certificate without associated private keys, if any. The output file will contain a single X.509 certificate encoded according to DER-encoding rules. The file won't be shrouded (encrypted). The data is presented in a binary file, so it won't be suitable for pasting into a textual body of an e-mail message or a web page. To export a certificate to a textual file, choose "Base-64 encoded  X.509 (.CER)" format. If a certificate being exported also contains a private key, the key may also be exported to a separate binary file in an unshrouded, unencrypted format corresponding to a PKCS#1 DER-encoded RSA private key. You will only need to enter the passphrase. The passphrase will be cached for subsequent exports of the certificate if Cache certificate passphrases/keys option is enabled..

Base-64 encoded X.509 (.CER)

This format is based on "DER encoded binary X.509", but it is additionally encoded with a Base64-wrapper, which slightly increases the file size. The file will only contain alphanumeric and other printable characters, making it suitable for including into the textual body of an e-mail message or a web page. Additionally, not all software applications can handle "DER encoded binary X.509" format when importing certificates, but "Base-64 encoded X.509" is more commonly accepted. If a certificate is exported it also contains a private key. This key may also be exported to a separate file, in the same way as "DER encoded binary X.509", with the exception that the format of a file containing the key will be textual only.

Include all the certificates in the certification path if possible

If this option is checked, all the certificates from the certification chain will be exported along with each exported certificate. A certification chain contains all the certificates used to certify (sign) a particular certificate. Without having the full chain, it's impossible to verify a certificate. That's why it's important to include all certificates. Please check this option if you are unsure if the destination system already has the full chain, which allows you to verify a certificate that you are going to export. But if The Bat! itself doesn't have the certificates required to build a full chain, only the available certificates will be included in the export file.

This option only works for formats that support multiple certificates in a single file, i.e. "Personal Information Exchange - PKCS #12 (.PFX)" and "Cryptographic Message Syntax Standard - PKCS #7 (.P7B)"

Export private keys as well

This option indicates that if selected certificates have associated private keys, those keys should be exported as well. This option is not supported for "Cryptographic Message Syntax Standard - PKCS #7 (.P7B)" output format.


Select X.509 Name Attributes Dialog

This dialog box allows you to choose which information should be included in a certificate that you are about to generate. The information is split into individual items (name attributes), each item has a X.509-specific type and a string value. The Bat! collects all the information from your address entry (vCard file) and creates corresponding items. Please note that name attribute types are specific to the X.509 standard and are named differently from field types in The Bat!'s address entry, but The Bat! tries to find a corresponding attribute type for every string in your address entry. For example, if you've put "London" in the "City" field of your vCard, The Bat! creates an X.509 Item of type "localityName" and value "London".

The meaning of each name attribute type is not discussed here, each CA may set their own rules as to how particular name attributes are treated. But there are two attributes that are treated similarly by most CAs: "commonName" (your full name) and "emailAddress" (your e-mail address).

Each name attribute contains a checkbox indicating whether this attribute should be included in the certificate. Unchecking an attribute has the same effect as if the item has been deleted from the list.

You can also add new attributes. Just click the "New" button and select the attribute type from the drop-down list. A new item with an empty value will appear. Select the item and type the value in the edit line in the bottom of the dialog box. Similarly, you can edit the values of other items as well.

Please note that according to X.509, all national characters will be encoded in the Unicode character set. Thus the "Windows User Interface Controls" list of items and the "Value" edit line work in Unicode mode. If there is a configuration problem (e.g. the required input locale was not properly installed in Microsoft Windows, or the system-default font doesn't contain the required characters), you may see question marks or square boxes instead of some characters. Please also note that the edit line is implemented using the Window RichEdit v2 component (although v3 is preferable). If you have problems with the edit line, try to upgrade the RichEdit component.


RSA Key Pair Size

When generating your S/MIME certificate, you'll be asked to specify the key size for your new certificate. As a rule of thumb, larger keys are more secure but slower. Smaller keys do decryption, encryption, verification and signatures much quicker than larger keys. For most applications, 1024 bit keys are quite sufficient. Keys larger than 2048 bits may not be interpreted by some S/MIME implementations. Also, it will take a  considerable amount of time to generate very large keys (3072 bits and more). Keys smaller than 768 bits are recommended for testing purposes only and are not considered to be secure by today's standards.


Date/Time format specifiers

Date/Time Format Strings are composed from specifiers that represent values to be inserted into the formatted string. Some specifiers (such as "d"), simply format numbers or strings. Other specifiers (such as "/") refer to locale-specific strings from system settings.

In the following table, specifiers are given in lower case. Case is ignored in formats, except for the "am/pm" and "a/p" specifiers. "Short" and "long" formats means the corresponding date and time formats set in the system country settings.

Specifier	Displays

c	Displays the date using the short format, followed by the time using the long format. The time is not displayed if the date-time value indicates midnight precisely.

d	Displays the day as a number without a leading zero (1-31).

dd	Displays the day as a number with a leading zero (01-31).

ddd	Displays the day as an abbreviation (Sun-Sat).

dddd	Displays the day as a full name (Sunday-Saturday).

ddddd	Displays the date using the short format.

dddddd	Displays the date using the long format.

e	Displays the year in the current period/era as a number without a leading zero (Japanese, Korean and Taiwanese locales only).

ee	Displays the year in the current period/era as a number with a leading zero (Japanese, Korean and Taiwanese locales only).

g	Displays the period/era as an abbreviation (Japanese and Taiwanese locales only).

gg	Displays the period/era as a full name. (Japanese and Taiwanese locales only).

m	Displays the month as a number without a leading zero (1-12). If the m specifier immediately follows an h or hh specifier, the minute rather than the month is displayed.

mm	Displays the month as a number with a leading zero (01-12). If the mm specifier immediately follows an h or hh specifier, the minute rather than the month is displayed.

mmm	Displays the month as an abbreviation (Jan-Dec).

mmmm	Displays the month as a full name (January-December).

yy	Displays the year as a two-digit number (00-99).

yyyy	Displays the year as a four-digit number (0000-9999).

h	Displays the hour without a leading zero (0-23).

hh	Displays the hour with a leading zero (00-23).

n	Displays the minute without a leading zero (0-59).

nn	Displays the minute with a leading zero (00-59).

s	Displays the second without a leading zero (0-59).

ss	Displays the second with a leading zero (00-59).

z	Displays the millisecond without a leading zero (0-999).

zzz	Displays the millisecond with a leading zero (000-999).

t	Displays the time using the short format.

tt	Displays the time using the long format.

am/pm	Uses the 12-hour clock for the preceding h or hh specifier, and displays 'am' for any hour before noon, and 'pm' for any hour after noon. The am/pm specifier can use lower, upper, or mixed case, and the result is displayed accordingly.

a/p	Uses the 12-hour clock for the preceding h or hh specifier, and displays 'a' for any hour before noon, and 'p' for any hour after noon. The a/p specifier can use lower, upper, or mixed case, and the result is displayed accordingly.

ampm	Uses the 12-hour clock for the preceding h or hh specifier, and displays the strings set for AM/PM accordingly to the system locale settings.

/	Displays the date separator character.

:	Displays the time separator character.

'xx'/"xx"	Characters enclosed in single or double quotes are displayed as-is, and do not affect formatting.


View S/MIME certificates

This window is your front end view of the structure of a certificate. If a certificate is invalid, this view will help you to determine why that is so.

The certificate view offers a tabbed view of the following properties of the certificate.

General

This view gives you general information about the certificate and its validity. You can find out who the certificate belongs to, who issued the certificate and the date range during which the certificate will remain valid. There is a button on this view that allows you to add any viewed certificate to the Address book. Any certificates not already held in the address book (including those in the 'Certification Path') will be added to the address book when  you press this button.

Details

This view shows you the various fields that make up the certificate and the values assigned to those fields. Items included in this view are things like:

•	Version - The S/MIME certificate version identifier.

•	Serial Number - A serial number for the certificate.

•	Signature Algorithm - The calculation method used in producing a signature from this certificate.

•	Issuer - The full details of the authority that issued this certificate.

•	Valid from - The first date from which this certificate is valid.

•	Valid to - The last date on which this certificate will be valid.

•	Subject - The email addresses associated with this certificate.

There may be other fields and other certificates may have different names for these fields, but this is a reasonable summary of what may appear in this view.

Certification Path

This view will show you the cascading path leading to the personal certificate from the issuing authority.


Electronic mail address
E-mail Address

On the Internet, each user has a unique address (some people have more than one e-mail address) which identifies the mail server or zone address, and the name of the mailbox. The usual structure of an e-mail address is <user name>@<mail server/zone>, e.g., john.smith@ritlabs.com. E-mail addresses cannot be anything like "John Smith" or "John Smith from Magic Island"


Internet

The Internet is a computer network, covering the entire globe. The Internet emanates from a core and ensures the correct interconnection of different information networks, belonging to various organisations around the world.

The first networks were used solely for the transmission of files and e-mail, but today it resolves the more complex problems of shared access to resources. Several years ago, programs were created to support the necessary functions of network search, and access to shared information resources and electronic archives.

The Internet was initially only used by research groups and educational establishments whose interests included remote access to supercomputers. These resources all became very popular in the business world, and in no time the Internet has grown phenomenally to the point where it is seen as a primary Business to Business (B2B) communications tool and an essential marketing resource and a major global market place.

Big companies were seduced by this quick and easy global connection, well suited to group-work, centralised programs and a single database accessed across Internet network connections. They considered a global network as an addendum to their own local networks. With the low service costs (often only a fixed monthly charge for lines used, or telephone charges) users are able to gain access to commercial and non-profit information services from anywhere in the world. Using the Internet it is possible to find information on practically any area of human activity, in the "free access" archives, from new scientific openings, to the weather forecast for tomorrow.

Besides all this, the Internet offers a unique potential for cheap, reliable and confidential global communication with the whole world. In practice, this turns out to be an extremely efficient communication method for multinational and multi-homed companies with various sites around the world; for international corporations, and other organisations. Usually, using an Internet infrastructure for international communications is vastly cheaper than direct computer communication through satellite links or telephone lines.

E-mail is the most widespread service on the Internet. Sending e-mail messages over the Internet is vastly cheaper than any other conventional communication medium. Besides, messages sent on the Internet will usually arrive in minutes (or, in the worst case, hours), while other messages (snail mail) can get to the addressee several days later, or even several weeks later.